CarsPoint Backend

graph TB
    subgraph "Presentation Layer"
        Controllers["Controllers"]
    end

    subgraph "Business Layer"
        Services["Services"]
        Guards["Guards & Policies"]
    end

    subgraph "Data Access Layer"
        Repositories["Repositories"]
        Entities["Entities"]
    end

    subgraph "Infrastructure"
        Cache[("Redis Cache")]
        DB[("MySQL Database")]
        Storage[("File Storage")]
        Queue["Bull Queue"]
    end

    Controllers --> Services
    Services --> Guards
    Services --> Repositories
    Repositories --> Entities
    Entities --> DB
    Services --> Cache
    Services --> Storage
    Services --> Queue
                

graph LR
    Auth["Auth Module"] --> User["User Module"]
    Auth --> Notification["Notification Module"]
    Car["Car Module"] --> Company["Company Module"]
    Car --> Upload["Upload Module"]
    Company --> Location["Location Module"]
    Customer["Customer Module"] --> Car
    Upload --> Shared["Shared Module"]
                

sequenceDiagram
    participant Client
    participant Guard as Auth Guard
    participant CASL as CASL Guard
    participant Controller
    participant Service
    participant DB as Database

    Client->>Guard: HTTP Request + JWT
    Guard->>Guard: Validate Token
    Guard->>CASL: Check Permissions
    CASL->>Controller: Authorized
    Controller->>Service: Call Method
    Service->>DB: Query/Mutate
    DB-->>Service: Result
    Service-->>Controller: DTO
    Controller-->>Client: JSON Response
                

sequenceDiagram
    participant User
    participant API as Auth API
    participant Service as Auth Service
    participant DB as Database
    participant Cache as Redis

    User->>API: POST /auth/login
    API->>Service: login(phone, password)
    Service->>DB: Find user by phone
    DB-->>Service: User record
    Service->>Service: Verify password (bcrypt)
    Service->>Service: Generate JWT access token
    Service->>Service: Generate refresh token (UUID)
    Service->>DB: Store hashed refresh token
    Service->>Cache: Cache user session
    Service-->>API: Tokens + User
    API-->>User: 200 OK
                

sequenceDiagram
    participant User
    participant API
    participant Service
    participant Cache as Redis
    participant SMS

    User->>API: POST /auth/login
    API->>Service: login()
    Service->>Service: Validate credentials
    Service->>Service: Check is2FAenabled = true
    Service->>Service: Generate 6-digit OTP
    Service->>SMS: Send OTP via SMS
    Service->>Cache: Store 2FA session (5 min TTL)
    Service-->>API: requires2FA: true
    API-->>User: 2FA Required

    User->>API: POST /auth/verify-2fa
    API->>Service: verify2FA(token, otp)
    Service->>Cache: Get 2FA session
    Service->>Service: Verify OTP (bcrypt)
    Service->>Cache: Delete 2FA session
    Service->>Service: Generate tokens
    Service-->>API: Tokens + User
    API-->>User: 200 OK
                

graph TD
    SA["Super Admin"] --> DA["Dealer Admin"]
    DA --> ST["Staff"]
    DA --> AU["Auditor"]
    SA --> CU["Customer"]

    SA -->|"Manage ALL"| ALL["All Resources"]
    DA -->|"Manage Company"| COMP["Company Resources"]
    ST -->|"Create Own"| OWN["Own Resources"]
    AU -->|"Read Only"| READ["Company Data"]
    CU -->|"Public Access"| PUB["Public + Own Data"]
                

sequenceDiagram
    participant Request
    participant AuthGuard
    participant CaslGuard
    participant CompanyGuard
    participant Controller

    Request->>AuthGuard: JWT Token
    AuthGuard->>AuthGuard: Validate & decode JWT
    AuthGuard->>CaslGuard: User context

    CaslGuard->>CaslGuard: Build ability for role
    CaslGuard->>CaslGuard: Check @CheckPolicies

    CaslGuard->>CompanyGuard: Authorized
    CompanyGuard->>CompanyGuard: Check @RequireCompany
    CompanyGuard->>Controller: Execute handler
                

flowchart TD
    A["POST /car"] --> B{"Authenticated?"}
    B -->|No| C["401 Unauthorized"]
    B -->|Yes| D{"Has permission?"}
    D -->|No| E["403 Forbidden"]
    D -->|Yes| F["Resolve company from session"]
    F --> G{"Company resolved?"}
    G -->|No| H["403 Company required"]
    G -->|Yes| I["Validate brand"]
    I --> J["Start transaction"]
    J --> K["Create car record"]
    K --> L["Commit transaction"]
    L --> M["Return car data"]
                

erDiagram
    Company ||--o{ Car : "has"
    Company ||--o{ User : "employs"
    Company ||--o| Location : "located at"

    Company {
        uuid id PK
        string name
        string email UK
        string phoneNumber
        enum companyLevel
        json socialHandle
        int yearsOfExperience
        string companyLogo
        boolean isActive
    }

    Location {
        uuid id PK
        string city
        string country
        string physicalAddress
        decimal latitude
        decimal longitude
    }
                

flowchart TD
    A["Client uploads file"] --> B["UploadController"]
    B --> C["ImageProcessor"]
    C --> D{"Validate image"}
    D -->|Invalid| E["400 Error"]
    D -->|Valid| F["Resize & Compress"]
    F --> G["Convert format"]
    G --> H{"Storage Provider?"}
    H -->|Local| I["LocalStorageService"]
    H -->|S3| J["S3StorageService"]
    I --> K["Save metadata to DB"]
    J --> K
    K --> L["Invalidate cache"]
    L --> M["Return upload info"]
                

flowchart TD
    subgraph "Notification Service"
        A["sendSMS / sendEmail"] --> B{"Get active driver"}
    end

    subgraph "SMS Drivers"
        B --> C1["Twilio"]
        B --> C2["Brevo"]
        B --> C3["Africa's Talking"]
        B --> C4["Termii"]
        B --> C5["Console"]
    end

    subgraph "Email Drivers"
        B --> D1["SMTP"]
        B --> D2["Brevo"]
        B --> D3["Console"]
    end

    C1 & C2 & C3 & C4 & C5 --> E["Track delivery status"]
    D1 & D2 & D3 --> E
                

flowchart LR
    A["Customer"] -->|Save| B["POST /customer/saved-cars/:carId"]
    A -->|Unsave| C["DELETE /customer/saved-cars/:carId"]
    A -->|List| D["GET /customer/saved-cars"]

    B --> E[("saved_cars table")]
    C --> E
    D --> E
                

flowchart TD
    subgraph "Call Requests"
        A1["Customer"] -->|"Wants callback"| B1["Create request"]
        B1 --> C1["PENDING"]
        C1 --> D1["CONTACTED"]
        D1 --> E1["COMPLETED"]
    end

    subgraph "Dealer Applications"
        A2["New Dealer"] -->|"Apply"| B2["Submit application"]
        B2 --> C2["PENDING"]
        C2 --> D2["UNDER_REVIEW"]
        D2 --> E2["APPROVED / REJECTED"]
    end

    subgraph "Financial Quotes"
        A3["Customer"] -->|"Finance inquiry"| B3["Submit request"]
        B3 --> C3["PENDING"]
        C3 --> D3["QUOTED"]
        D3 --> E3["CLOSED"]
    end
                

sequenceDiagram
    participant Customer
    participant API
    participant DB
    participant Dealer

    Customer->>API: POST /call-request
    Note over API: No auth required
    API->>DB: Create status: PENDING
    API-->>Customer: Request submitted

    Dealer->>API: GET /call-request
    API->>DB: Query requests
    API-->>Dealer: Pending requests

    Dealer->>API: PATCH /call-request/:id
    API->>DB: Update status
    API-->>Dealer: Updated