# Technical Architecture Draft

## Architecture Goals
- Field-first performance in poor network conditions.
- Reliable workflow state transitions with auditability.
- Fast management visibility without manual data consolidation.

## System Components
1. **Mobile App (Android first, iOS second)**
   - Offline local store
   - Camera, voice input, drawing pin capture
   - Background sync queue
2. **API Gateway**
   - AuthN/AuthZ, request validation, tenant routing
3. **Execution Core Services**
   - Daily Log Service
   - Task/Blocker Service
   - RFI Service
   - Punch/QA Service
4. **Workflow and SLA Engine**
   - State transition rules
   - Due date timers and escalation triggers
5. **Document and Drawing Service**
   - Drawing versioning, file metadata, pin references
6. **Notification Service**
   - Push, SMS/email fallback, digest notifications
7. **Analytics and Dashboard Service**
   - KPI aggregations and trend snapshots
8. **Data Layer**
   - Transaction DB (OLTP)
   - Event log/audit store
   - Read model cache for dashboards

## High-Level Data Flow
```mermaid
flowchart LR
  mobileApp[MobileAppOfflineFirst] --> syncQueue[SyncQueue]
  syncQueue --> apiGateway[ApiGateway]
  apiGateway --> executionServices[ExecutionCoreServices]
  executionServices --> workflowSla[WorkflowSlaEngine]
  executionServices --> drawingService[DrawingDocumentService]
  workflowSla --> notifyService[NotificationService]
  executionServices --> eventStore[EventAuditStore]
  eventStore --> analyticsService[AnalyticsDashboardService]
  analyticsService --> managementView[ManagementDashboard]
```

## Key Data Model (Minimal)
- `users` (role, site access, org)
- `projects` (client, site, stage)
- `locations` (zone, floor, area hierarchy)
- `daily_logs`
- `tasks_blockers`
- `rfis`
- `punch_items`
- `attachments`
- `workflow_events`
- `sla_breaches`

## Offline Sync Strategy
- Local-first writes with UUID-based temporary IDs.
- Sync protocol:
  1. enqueue local mutation
  2. send with idempotency key
  3. server ack with canonical ID/version
  4. client reconciles and marks success
- Conflict handling:
  - Last-write-wins for comments/notes
  - Server-side rule checks for status transitions
  - Manual merge queue for hard conflicts

## Security and Compliance
- Role-based policy enforcement at API layer.
- Every status change logged in immutable audit stream.
- Attachment access controlled by project and role scope.
- Signed URLs for file upload/download with short expiry.

## Performance SLO Targets
- Mobile log form load < 2s on mid-range Android.
- Create task/RFI/punch action confirmation < 1.5s online.
- Sync retry backoff with max 5 minutes between attempts.
- Dashboard refresh interval: near real-time, <= 5 minutes.

## Suggested Technology Baseline
- Mobile: React Native or Flutter (offline plugin ecosystem maturity required)
- Backend: Node.js/TypeScript or Go microservices
- Database: PostgreSQL + Redis cache
- File storage: S3-compatible object storage
- Messaging: queue-based worker for SLA timers and notifications

## Deployment Phases
- Phase 1: single-region managed cloud deployment for pilot.
- Phase 2: add background worker autoscaling and read replica.
- Phase 3: multi-project tenancy hardening and DR strategy.