Skip to content
M
Merq

Architecture Diagrams

Architecture Diagrams

Section titled “Architecture Diagrams”

This document contains high-level architecture diagrams for the Merq Field Force Management Platform.

High-Level System Architecture

Section titled “High-Level System Architecture”
flowchart TB
    subgraph Clients
        Mobile[("Mobile App\nReact Native")]
        Web[("Web Dashboard\nReact")]
    end

    subgraph Backend["Merq Backend (Go)"]
        API[("REST API\nGin Framework")]
        Auth[("Auth\nJWT")]
        RBAC[("RBAC\nMiddleware")]
        Business[("Business Logic\nServices")]
        Cache[("Redis Cache")]
    end

    subgraph Database
        PG[(PostgreSQL)]
        Redis[(Redis)]
    end

    subgraph External
        FCM[("Firebase\nFCM")]
        Maps[("Maps API\nGoogle/OSM")]
    end

    Mobile -->|HTTPS + JWT| API
    Web -->|HTTPS + JWT| API
    API --> Auth
    API --> RBAC
    API --> Business
    Business --> Cache
    Business --> PG
    Business --> FCM
    Business --> Maps
    Cache --> Redis

Data Flow Diagram

Section titled “Data Flow Diagram”
sequenceDiagram
    participant U as User
    participant A as API Gateway
    participant S as Service
    participant R as Repository
    participant D as Database
    participant C as Cache

    U->>A: Request + JWT
    A->>A: Validate JWT
    A->>S: Forward Request
    S->>C: Check Cache
    alt Cache Hit
        C-->>S: Return Cached Data
    else Cache Miss
        S->>R: Query
        R->>D: SQL Query
        D-->>R: Results
        R-->>S: Data
        S->>C: Store in Cache
    end
    S-->>A: Response
    A-->>U: JSON Response

Mobile Offline-First Architecture

Section titled “Mobile Offline-First Architecture”
flowchart LR
    subgraph Mobile["Mobile App"]
        UI[("UI Layer\nPaper MD3")]
        Query[("TanStack Query\nofflineFirst")]
        Store[("MMKV\nLocal Storage")]
    end

    subgraph Sync["Sync Layer"]
        Queue[("Offline Queue")]
        Conflict[("Conflict Resolution")]
    end

    subgraph Server["Backend"]
        API[("REST API")]
        PG[(PostgreSQL)]
    end

    UI --> Query
    Query --> Store
    Query -->|Online| API
    Query -->|Offline| Queue
    Queue -->|When Online| API
    API --> PG

Database Schema Overview

Section titled “Database Schema Overview”
erDiagram
    WORKSPACE ||--o{ USER : "has"
    WORKSPACE ||--o{ OUTLET : "contains"
    WORKSPACE ||--o{ PROJECT : "contains"
    WORKSPACE ||--o{ TEAM : "contains"
    
    PROJECT ||--o{ OUTLET_PROJECT : "relates"
    OUTLET ||--o{ OUTLET_PROJECT : "relates"
    
    OUTLET ||--o{ OUTLET_VISIT : "has"
    USER ||--o{ OUTLET_VISIT_ASSIGNEE : "assigned_to"
    OUTLET_VISIT ||--o{ OUTLET_VISIT_ASSIGNEE : "has"
    
    OUTLET_VISIT ||--o{ OUTLET_VISIT_SUBMISSION : "has"
    FORM ||--o{ OUTLET_VISIT_SUBMISSION : "is"
    
    USER ||--o{ ATTENDANCE : "logs"
    TEAM ||--o{ ATTENDANCE : "records"

Deployment Topology

Section titled “Deployment Topology”
flowchart TB
    subgraph Cloud["Cloud Provider"]
        LB[("Load Balancer")]
        
        subgraph Services
            Backend1[("Backend\nInstance 1")]
            Backend2[("Backend\nInstance 2")]
            BackendN[("Backend\nInstance N")]
        end
        
        DB[(PostgreSQL\nPrimary)]
        DB_Replica[(PostgreSQL\nReplica)]
        Redis[(Redis\nCluster)]
        
        Mobile[("Mobile Users")]
        Web[("Web Users")]
    end

    Mobile --> LB
    Web --> LB
    LB --> Backend1
    LB --> Backend2
    LB --> BackendN
    
    Backend1 --> Redis
    Backend2 --> Redis
    BackendN --> Redis
    
    Backend1 --> DB
    Backend2 --> DB
    BackendN --> DB
    
    DB --> DB_Replica

API Request Flow

Section titled “API Request Flow”
flowchart TD
    Start[("Client Request")] --> Auth{Authenticated?}
    Auth -->|No| 401[("401 Unauthorized")]
    Auth -->|Yes| Perms{Has Permission?}
    Perms -->|No| 403[("403 Forbidden")]
    Perms -->|Yes| Workspace{Workspace Valid?}
    Workspace -->|No| 404[("404 Not Found")]
    Workspace -->|Yes| Process[("Process Request")]
    Process --> Query[("DB Query")]
    Query --> Cache{Cache Valid?}
    Cache -->|Yes| ReturnCache[("Return Cached")]
    Cache -->|No| DBQuery[("Query Database")]
    DBQuery --> ReturnDB[("Return Data")]
    ReturnCache --> Response[("JSON Response")]
    ReturnDB --> Cache2[("Update Cache")]
    Cache2 --> Response
    
    style 401 fill:#ffcccc
    style 403 fill:#ffcccc
    style 404 fill:#ffcccc
    style Response fill:#ccffcc
Section titled “Related Documentation”