Fieldforce Management — Design Spec

System Architecture

flowchart TB
    subgraph surfaces["Two Surfaces — Same Features"]
        P["Panel (Desktop)\nSolidStart · /app/fieldforce/*\nTables · Bulk actions · Offset pagination"]
        M["Mobile Web\nAstro + Qwik · /fieldforce/*\nTouch-friendly · Camera · Cursor scroll"]
    end
    B["Backend (Bun + Go)\nExisting: Auth · Org · Members · Teams\nNew: ff_tasks · ff_activities · ff_attachments · AI endpoints"]
    C["ClawUI AI Gateway\nCost tracking per org · Audit logs · Multi-provider failover"]
    DB["PostgreSQL\nff_tasks · ff_activities · ff_attachments\nff_audit_logs · ff_task_embeddings · org_ai_configs"]

    P -->|"org_id-scoped API"| B
    M -->|"org_id-scoped API"| B
    B -->|"AI calls"| C
    B --> DB
    

Frontend Stack

Roles & Access Control

Data Model

Core Tables

ff_tasks

id, org_id, task_type ('service'|'sales'|'logistics'|string), title, description, location, due_date, priority ('low'|'medium'|'high'), status, created_by, assigned_to[] (JSONB), ai_checklist[] (JSONB), review_note

ff_activities

id, org_id, task_id, performed_by, activity_type ('note'|'photo'|'signature'|'status_update'|'checklist'), content, duration_minutes?, started_at?

ff_attachments

id, activity_id, file_url (S3 org-prefixed), file_type ('photo'|'signature'), ai_score 0–100?, ai_flags[]? — ai_score/flags Phase 3

ff_task_embeddings

id, task_id, org_id, embedding vector(1536), updated_at — pgvector; generated from title + description + location + task_type; kept in separate table to keep ff_tasks lean

ff_audit_logs

Append-only. id, org_id, user_id, user_name, user_role, action (AuditAction), entity_type 'FIELDFORCE_TASK', entity_id, before (JSONB)?, after (JSONB)?, details (JSONB)?, ip_address, user_agent, session_id, request_id

org_ai_configs

Org-level, shared across all AI modules. id, org_id (unique), mode ('trial'|'platform'|'byok'|'disabled'), provider, api_key_encrypted (AES-256), model, trial_credits_used, trial_credits_limit

Task Status Flow

flowchart LR
    P[pending] --> IP[in_progress]
    IP --> C[completed]
    C --> A[approved]
    C --> NR[needs_revision]
    NR --> IP
    P -.->|"cancel\nadmin/manager only"| CAN[cancelled]
    IP -.->|"cancel"| CAN
    C -.->|"cancel"| CAN
    NR -.->|"cancel"| CAN
    

AI Config Modes

Audit Log Events

type AuditedFieldforceService struct {
    inner       *FieldforceService
    auditHelper *AuditHelper
}

func (s *AuditedFieldforceService) ApproveTask(ctx context.Context, taskID string, note string) error {
    task, _ := s.inner.taskRepo.FindByID(ctx, taskID)
    before := task.Status                   // capture BEFORE

    err := s.inner.ApproveTask(ctx, taskID, note)

    s.auditHelper.LogTaskApproval(ctx, TaskAuditParams{
        TaskID:  taskID,
        Before:  before,
        After:   "approved",
        Details: map[string]any{"review_note": note},
    })                                      // non-blocking — audit errors don't fail operation

    return err
}

API Design

Task Endpoints

POST   /api/organizations/:org_id/fieldforce/tasks
         Body: { title, description, task_type, assigned_to[], due_date, priority, location? }

GET    /api/organizations/:org_id/fieldforce/tasks
         ?status&task_type&assignee_id&due_before&priority&q (full-text)&sort_by&sort_dir
         &page&page_size (Panel — offset)  |  &cursor&limit (Mobile — cursor)
         Returns: { tasks: Task[], total?, next_cursor? }

GET    /api/organizations/:org_id/fieldforce/tasks/:task_id
         Returns: Task + { activities: Activity[], attachments: Attachment[] }

PATCH  /api/organizations/:org_id/fieldforce/tasks/:task_id
         Body: { status?, assigned_to[]?, priority?, due_date?, … }

DELETE /api/organizations/:org_id/fieldforce/tasks/:task_id
         Soft-cancel. Requires manager/admin role.

Activity Endpoints

POST   /api/organizations/:org_id/fieldforce/activities
         Body: { task_id, activity_type, content, duration_minutes?, started_at? }

GET    /api/organizations/:org_id/fieldforce/activities
         ?task_id&performed_by

POST   /api/organizations/:org_id/fieldforce/activities/:activity_id/attachments
         Multipart or presigned S3 URL flow.

AI Endpoints

POST   /api/organizations/:org_id/fieldforce/ai/parse-task
         Body: { prompt: string }
         Returns: Partial<Task> (title, description, task_type, priority, due_date, location, assignee suggestions)

POST   /api/organizations/:org_id/fieldforce/ai/suggest-assignees
         Body: { task_id or partial task fields }
         Returns: { suggestions: [{ user_id, name, reason, score }] }

POST   /api/organizations/:org_id/fieldforce/ai/completion-summary
         Body: { task_id }
         Returns: { summary: string }

POST   /api/organizations/:org_id/fieldforce/ai/transcribe-voice
         Body: { audio_blob }
         Returns: { transcript: string }

GET    /api/organizations/:org_id/fieldforce/ai/at-risk-tasks
         Returns: [{ task_id, risk_score, reason }]

Audit Log Endpoints

GET    /api/organizations/:org_id/fieldforce/audit
         Scoped by role: admin/manager = all org; supervisor = own team only.
         ?task_id&actor_id&action&from&to&page&page_size
         Returns: { logs: AuditLog[], total }

GET    /api/organizations/:org_id/fieldforce/audit/tasks/:task_id
         Full audit trail for one task. Returns: AuditLog[]

# No write endpoints — audit logs are system-generated only.

AI Config Endpoints

GET    /api/organizations/:org_id/ai-config          # api_key_encrypted NEVER returned
PUT    /api/organizations/:org_id/ai-config          # Admin/Owner only
DELETE /api/organizations/:org_id/ai-config/api-key  # Remove BYOK key, revert to platform/trial

# Platform admin only:
GET    /api/admin/ai-config/defaults
PUT    /api/admin/ai-config/defaults                 # Set default provider, model, trial credits limit

Panel Features (Desktop)

Home Dashboard — /app/fieldforce

Task List — /app/fieldforce/tasks

• Full table: title, task_type, assignee(s), priority, due_date, status
• Full-text search across title + description + assignee name
• Filters: status, task_type, priority, assignee, due date range
• Sort: due_date, priority, created_at, status
• Offset pagination — configurable page size: 20 / 50 / 100
• Bulk actions: reassign, cancel, change priority, extend deadline
• Overdue tasks: visual red flag + row highlight

Task Detail — /app/fieldforce/tasks/:id

• Full task metadata · Assigned team members with avatars · Location string (clickable → open in maps)
• AI-generated checklist — editable before publishing
• Approval panel (manager/supervisor): approve or reject with feedback text
• On rejection: status → needs_revision, feedback surfaced to field team
• AI completion summary button — one-click professional report generation
• Audit trail tab: full event history for this task (actor, action, before/after, timestamp)
• Visual Task Timeline: merged chronological view of ff_activities + ff_audit_logs, read-only for all roles

Create Task — /app/fieldforce/tasks/new

Audit Log — /app/fieldforce/audit

Access: Admin / Owner / Manager only. Table view: actor, action, task, before → after, timestamp. Filters: action type, actor, task_id, date range. Offset pagination. Each row expandable for full before/after JSON diff. Approval events color-coded. Export to CSV (Phase 2).

Mobile Web Features

Home — /fieldforce

My Tasks — /fieldforce/tasks

• Task cards with large tap targets
• Cursor-based infinite scroll
• Filter chips: All / Pending / In Progress / Overdue
• Sort: Due date / Priority

Task Detail — /fieldforce/tasks/:id

• Task context: what, where, when, assigned by
• AI checklist with tap-to-tick items
• Visual Task Timeline — stacked card format optimized for mobile scroll; color-coded dots per event; photos as inline thumbnails; tap any card to expand full detail
• Log Activity button → bottom sheet

Log Activity — Bottom Sheet

Status Update

Field team taps status toggle → confirm dialog → API call → manager/supervisor notified. completed status triggers push + in-app notification to manager/supervisor for review.

AI Features

flowchart LR
    REQ["AI Request"] --> GW["ClawUI Gateway"]
    GW -->|"platform mode"| PK["Platform API key\nplatform default provider"]
    GW -->|"byok mode"| OK["Decrypt org API key\norg chosen provider"]
    GW -->|"trial mode"| TK["Platform API key\ndeduct credit"]
    GW -->|"disabled"| E["403 — AI not available"]
    

MVP AI Features (Phase 2)

Phase 3 & Phase 4 AI Features

Supported AI Providers

Platform admin sets the default provider + model for platform/trial modes. Orgs on BYOK select their own provider and model. Org Admin/Owner configures via Panel → Org Settings → AI.

Search & Pagination

Panel URL (offset)

GET /fieldforce/tasks?q=broken+ac+unit&page=2&page_size=50&sort_by=due_date&sort_dir=asc

Mobile URL (cursor)

GET /fieldforce/tasks?q=broken+ac+unit&cursor=<opaque_token>&limit=20

Sort controls

due_date, priority, created_at, status, updated_at

Notifications

Reuses existing push notification infrastructure (PushNotificationToggle in Astro app) + in-app notification feed.

Overdue Task Handling

Background job / cron checks: due_date < now AND status NOT IN (completed, approved, cancelled).

1. Flag as overdue

   Add visual overdue flag — red badge in task list and task detail.

2. Notify

   Push + in-app to assigned field team + manager/supervisor.

3. Auto-escalate

   If overdue > 24h with no activity: escalate to next role up — supervisor → manager → admin. Logged as TASK_ESCALATED in audit trail.

4. Surface proactively (AI)

   GET /ai/at-risk-tasks surfaces tasks likely to miss deadline before they become overdue — shown in manager dashboard.

Offline-First Architecture (Mobile Web Only)

// Defined once in Phase 1. Components only ever call this interface.
interface FieldforceStorageAdapter {
  getTasks(orgId: string): Promise<Task[]>
  getTask(taskId: string): Promise<Task | null>
  cacheTasks(tasks: Task[]): Promise<void>
  queueActivity(activity: PendingActivity): Promise<void>
  queueAttachment(attachment: PendingAttachment): Promise<void>
  getSyncQueue(): Promise<PendingSync[]>
  clearSynced(ids: string[]): Promise<void>
}

// Phase 2: IndexedDB (Dexie.js)
class IndexedDBAdapter implements FieldforceStorageAdapter { … }

// Phase 4: Electric SQL (drop-in replacement)
class ElectricSQLAdapter implements FieldforceStorageAdapter { … }

1. Phase 1 — Interface only

   FieldforceStorageAdapter interface defined. Components coded against it. No IndexedDB activated.

2. Phase 2 — IndexedDB read

   IndexedDBAdapter (Dexie.js) activated. db.tasks populated (read-only cache). db.activities + db.attachments pending queues. db.sync_log for reconnect sync. Conflict resolution: last-write-wins on append-only activity logs.

3. Phase 4 — Electric SQL

   Implement ElectricSQLAdapter, swap in DI container, one-time data migration (IndexedDB → SQLite on app load). Real-time PostgreSQL sync, full offline read/write.

Implementation Phases

1. Phase 1 — Core Task Dispatch (Weeks 1–3)

   DB schema (all 6 tables) · Task CRUD · Activity creation · Audit logs for: created, assigned, status changed, cancelled · Panel: task list, task detail with audit tab, create form, activity log overview, audit log page · Mobile: my tasks, task detail, text note logging · Notifications: assigned + completed · Calendar: tasks on /team/calendar · i18n: en/zh/ms · FieldforceStorageAdapter interface defined (IndexedDB schema inactive)

2. Phase 2 — AI Core + Approval (Weeks 4–6)

   All 7 MVP AI features via ClawUI · Photo upload (camera + S3) · Signature pad (canvas Qwik island) · Manager approval workflow (approve / reject / needs_revision) · Remaining audit events · Overdue cron + escalation · At-risk task notifications · Panel: AI task creation mode, smart assignment panel, completion summary · Mobile: voice logging, AI checklist tick

3. Phase 3 — Polish + Phase 2 AI (Weeks 7–8)

   Photo analysis + quality score · Route optimization · Anomaly detection · Workload rebalancing · Manager daily briefing · Mobile UX refinement (gesture tuning, touch targets) · Qwik bundle analysis + optimization · IndexedDB read-only task cache activated

4. Phase 4 — Offline + Advanced (Future)

   Full offline sync (ElectricSQLAdapter + real-time PostgreSQL sync) · Hall Chat conversational interface · Analytics / reporting dashboard · Data export (CSV, PDF) · Location map pins · Custom task_type per org · Per-subscription billing controls

SaaS Considerations

Resolved Open Questions

Qwik vs Solid for mobile?

Qwik — already in Astro app, consistent with existing platform

One portal or two?

Two surfaces (Panel + Mobile), same API, role controls access

Offline in MVP?

Architecture ready (FieldforceStorageAdapter interface + IndexedDB schema defined), no sync logic in MVP

Location format?

Plain address string in MVP; lat/lng map pin Phase 2

Task type?

task_type: 'service' | 'sales' | 'logistics' | string — open string allows custom types

Supervisor scope?

Team-scoped. Admin/Owner sees all.

Module activation?

Default ON, feature flag per org — platform admin can disable

AI routing?

All AI calls through ClawUI middleware — no surface calls a provider directly

Calendar integration?

Tasks with due_date appear on existing /team/calendar; color-coded by priority; click navigates to task detail