LynkedUpPro_CRM/docs/diagrams/hld.md

# HLD — High-Level Design Diagrams

**Scope:** LynkedUpPro CRM — Full System
**Renders in:** GitHub, VS Code (Mermaid extension), GitLab, Notion

---

## Diagram 1 — System Context

Who uses the system, what it does, and what external services it depends on.

```mermaid
graph TB
    subgraph Users["👤 User Roles"]
        OWN([Owner])
        ADM([Admin])
        FA([Field Agent])
        CON([Contractor])
        SUB([Subcontractor])
        VEN([Vendor])
        CUS([Customer])
    end

    subgraph LynkedUpPro["🏢 LynkedUpPro System"]
        FE["React 19 SPA\n(Vercel)"]
        BE["FastAPI Backend\n(Railway / Render)"]
        DB[(PostgreSQL 16)]
    end

    subgraph External["☁️ External Services"]
        GROQ["Groq API\n(AI / LLM)"]
        S3["AWS S3\n(File Storage)"]
        SMTP["SendGrid\n(Email)"]
    end

    OWN & ADM & FA & CON & SUB & VEN & CUS -->|"HTTPS browser"| FE
    FE -->|"REST /api/v1/ + JWT"| BE
    BE -->|"SQLAlchemy async"| DB
    BE -->|"httpx proxy"| GROQ
    BE -->|"boto3 SDK"| S3
    BE -->|"SMTP / SendGrid SDK"| SMTP
```

---

## Diagram 2 — System Components

Internal components of each layer and how they connect.

```mermaid
graph LR
    subgraph Frontend["Frontend — React SPA (Vite)"]
        direction TB
        AC["AuthContext\n(login / logout)"]
        MS["mockStore → ApiProvider\n(data layer)"]
        GC["GamificationContext\n(XP / levels)"]
        PAGES["Pages\n(Owner / Admin / Agent\nContractor / Vendor / Customer)"]
        CHAT["Chatbot Component\n(AI assistant)"]
        MAP["Maps Component\n(Leaflet + Polygons)"]
    end

    subgraph Backend["Backend — FastAPI"]
        direction TB
        MW["Middleware\n(CORS · Rate Limit · Logging)"]
        AUTH_R["Auth Router\n(/api/v1/auth)"]
        ROUTERS["Feature Routers\n(properties · meetings · vendors\nprojects · invoices · documents\nusers · chatbot)"]
        SERVICES["Service Layer\n(business logic)"]
        DEPS["Dependencies\nget_db · get_current_user\nrequire_role()"]
    end

    subgraph Data["Data Layer"]
        PG[(PostgreSQL\n16 tables)]
        S3_B["AWS S3\n(documents / COIs)"]
    end

    subgraph Ext["External APIs"]
        GROQ_A["Groq API\nqwen-32b"]
        SG["SendGrid\n(alerts)"]
    end

    Frontend -->|"JWT Bearer / httpOnly cookie"| MW
    MW --> AUTH_R
    MW --> ROUTERS
    AUTH_R --> DEPS
    ROUTERS --> DEPS
    DEPS --> SERVICES
    SERVICES --> PG
    SERVICES --> S3_B
    SERVICES -->|"RBAC-gated proxy"| GROQ_A
    SERVICES -->|"async trigger"| SG
```

---

## Diagram 3 — Role Access Zones

Which roles can access which portals and routes. Each role logs in through a single `/login` page and is routed to their portal based on JWT claims.

```mermaid
graph TD
    LOGIN["/login\nSingle Entry Point"]

    LOGIN -->|"role = OWNER"| OWNER_ZONE
    LOGIN -->|"role = ADMIN"| ADMIN_ZONE
    LOGIN -->|"role = FIELD_AGENT"| FA_ZONE
    LOGIN -->|"role = CONTRACTOR"| CON_ZONE
    LOGIN -->|"role = VENDOR"| VEN_ZONE
    LOGIN -->|"role = SUBCONTRACTOR"| SUB_ZONE
    LOGIN -->|"role = CUSTOMER"| CUS_ZONE

    subgraph OWNER_ZONE["👑 Owner Portal"]
        O1["/owner/snapshot\nBusiness Health Dashboard"]
        O2["/owner/projects\nProject Command Center"]
        O3["/owner/vendors\nVendor Directory"]
        O4["/owner/people\nPeople Directory"]
        O5["/owner/documents\nDocument Management"]
        O6["/owner/maps\nTerritory Map"]
        O7["/owner/pro-canvas\nTeam Leaderboard"]
        O8["/admin/*\nFull Admin Access"]
    end

    subgraph ADMIN_ZONE["🏢 Admin Portal"]
        A1["/admin/dashboard\nCommand Center"]
        A2["/admin/schedule\nTeam Schedule"]
        A3["/admin/leaderboard\nSales Leaderboard"]
        A4["/admin/maps\nTerritory Map"]
        A5["/admin/pro-canvas\nTeam Performance"]
    end

    subgraph FA_ZONE["🚶 Field Agent Portal"]
        FA1["/emp/fa/dashboard\nMy Dashboard"]
        FA2["/emp/fa/maps\nTerritory Map"]
        FA3["/emp/fa/pro-canvas\nMy Gamification Hub"]
    end

    subgraph CON_ZONE["🔨 Contractor Portal"]
        C1["/contractor/dashboard\nMy Projects"]
        C2["/contractor/projects\nProject List"]
    end

    subgraph VEN_ZONE["📦 Vendor Portal"]
        V1["/vendor/dashboard\nMy Orders & KPIs"]
        V2["/vendor/orders\nOrder Management"]
    end

    subgraph SUB_ZONE["⚙️ Subcontractor Portal"]
        S1["/subcontractor/dashboard\nMy Work"]
        S2["/subcontractor/projects\nAssigned Projects"]
    end

    subgraph CUS_ZONE["🏠 Customer Portal"]
        CU1["/portal/profile\nMy Property & Meetings"]
    end

    SHARED["/chat-assistant\nAI Assistant\n(all roles)"]
    LOGIN --> SHARED
```

---

## Diagram 4 — High-Level Data Flow

How a user action travels from browser → API → database and back.

```mermaid
sequenceDiagram
    actor User as 👤 User (any role)
    participant FE as React SPA
    participant AC as AuthContext
    participant API as FastAPI /api/v1
    participant DB as PostgreSQL

    Note over User,DB: ── Initial Login ──
    User->>FE: Enter credentials
    FE->>AC: login(identifier, password, type)
    AC->>API: POST /auth/login
    API->>DB: SELECT user WHERE email/empId = ?
    DB-->>API: User row
    API-->>AC: { access_token, refresh_token, user }
    AC-->>FE: Set cookie + update user state
    FE-->>User: Redirect to role portal

    Note over User,DB: ── Authenticated Data Request ──
    User->>FE: Navigate to page
    FE->>API: GET /properties?status=Hot+Lead\nAuthorization: Bearer <token>
    API->>API: Validate JWT → extract role
    API->>API: require_role(FIELD_AGENT, ADMIN, OWNER)
    API->>DB: SELECT * FROM properties WHERE deleted_at IS NULL
    DB-->>API: Rows
    API-->>FE: { data: [...], meta: { total, page } }
    FE-->>User: Render page with data

    Note over User,DB: ── Write Action (e.g. assign agent) ──
    User->>FE: Click "Assign Agent"
    FE->>API: PATCH /properties/42\n{ assigned_agent_id: "uuid" }
    API->>API: require_role(ADMIN, OWNER)
    API->>DB: UPDATE properties SET assigned_agent_id = ?, updated_at = NOW()
    API->>DB: INSERT INTO audit_logs (actor_id, action, ...)
    DB-->>API: Updated row
    API-->>FE: { data: { ...updatedProperty } }
    FE-->>User: Toast "Agent assigned ✓"
```

---

## Diagram 5 — Deployment Architecture

How the pieces are hosted and connected in production.

```mermaid
graph TB
    subgraph Internet["🌐 Internet"]
        BROWSER["User Browser"]
    end

    subgraph Vercel["Vercel (Frontend CDN)"]
        CDN["Static Assets\nReact SPA Bundle"]
    end

    subgraph Railway["Railway / Render (Backend)"]
        UVICORN["uvicorn workers\nFastAPI app"]
        PG_DB[("PostgreSQL 16\nManaged DB")]
    end

    subgraph AWS["AWS"]
        S3_BUCKET["S3 Bucket\nlynkeduppro-docs\n(COIs, W9s, Contracts)"]
    end

    subgraph ThirdParty["Third-Party APIs"]
        GROQ_API["Groq API\nLLM inference"]
        SENDGRID_API["SendGrid\nTransactional email"]
    end

    BROWSER -->|"HTTPS :443"| CDN
    CDN -->|"HTTPS /api/v1/*\nJWT in cookie"| UVICORN
    UVICORN <-->|"TCP :5432\nasyncpg"| PG_DB
    UVICORN -->|"HTTPS\npre-signed URLs"| S3_BUCKET
    UVICORN -->|"HTTPS\nAPI key"| GROQ_API
    UVICORN -->|"HTTPS\nAPI key"| SENDGRID_API
    BROWSER -->|"pre-signed URL\ndirect upload"| S3_BUCKET
```

---

## Diagram 6 — Role Permission Overview (RBAC Summary)

A simplified view of the data each role can read and write.

```mermaid
graph LR
    subgraph ReadAll["📖 Read All Data"]
        OWNER_R["OWNER\nAll tables, all records"]
        ADMIN_R["ADMIN\nAll tables, all records"]
    end

    subgraph ReadScoped["📖 Read Scoped Data"]
        FA_R["FIELD_AGENT\nOwn meetings + assigned properties"]
        CON_R["CONTRACTOR\nAssigned projects + own invoices"]
        SUB_R["SUBCONTRACTOR\nAssigned tasks + project scope"]
        VEN_R["VENDOR\nOwn orders + own compliance docs"]
        CUS_R["CUSTOMER\nOwn property + own meetings"]
    end

    subgraph WriteAll["✏️ Write All Data"]
        OWNER_W["OWNER\nProjects · Vendors · Documents\nInvoice approval · Change orders"]
        ADMIN_W["ADMIN\nProperties · Meetings · Assignments"]
    end

    subgraph WriteSelf["✏️ Write Own Data"]
        FA_W["FIELD_AGENT\nMeeting outcomes · Lead status"]
        VEN_W["VENDOR\nOrder acknowledgement"]
        CUS_W["CUSTOMER\nProfile info"]
    end

    OWNER_R --- OWNER_W
    ADMIN_R --- ADMIN_W
    FA_R --- FA_W
    VEN_R --- VEN_W
    CUS_R --- CUS_W
```