# codegirlsinc/frieghtflow architecture

> Architecture diagram of the GitHub repository codegirlsinc/frieghtflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codegirlsinc/frieghtflow
- Repository: https://github.com/codegirlsinc/frieghtflow

## Overview

##### Main components
- Frontend: This is built with Next.js and TailwindCSS. The file structure under the “frontend” directory shows organized pages (by features like “auth”, “dashboard”, “shipments”, etc.), components, hooks, and providers that form the user interface.
- Backend: Implemented in NestJS, the “backend” directory is organized by domain (modules such as Admin, auth, notifications, payments, pricing, shipments, users, and wallet). This indicates an MVC/microservice-like module structure handling business logic, authentication, and API endpoints.
- Database: Though not explicitly named in the file tree, the README indicates PostgreSQL is used. Ensure that the database is shown as a persistent store that the backend communicates with.
- Blockchain / Smart Contracts: The “contract/ffpay” directory contains Rust/ Cairo smart contracts targeting the StarkNet ecosystem. These contracts are responsible for key transactions like escrow payments, proof-of-delivery, and reputation management.
- External/Supporting Services: Highlight services like real-time notifications (likely via WebSockets, as mentioned in the README), GPS shipment tracking, and AI-powered analytics (for job matching) that integrate with the system.

##### Out their interactions
- The Frontend communicates with the Backend through API calls (including authentication, shipment management, payment processing, and notifications).
- The Backend provides RESTful (or GraphQL) endpoints that orchestrate business logic, interact with the PostgreSQL database, and communicate with the blockchain layer.
- When a transaction or key event occurs, the backend interacts with the smart contracts on StarkNet to execute on-chain operations (e.g., escrow payments, dispute resolution).
- Real-time interactions such as notifications and shipment tracking are managed by services within the backend that use WebSocket connections or similar frameworks.

##### Architectural patterns and design principles
- Modular Architecture: The backend’s structure (divided into Admin, auth, shipments, etc.) indicates a modular approach for easier scaling and maintenance.
- Separation of Concerns: Clear separation between frontend (UI and client-side logic), backend (business logic, REST APIs, and database operations), and blockchain smart contracts (on-chain logic).
- Web3 Integration: The blend of off-chain processing with on-chain smart contracts ensures both efficiency in data handling (via PostgreSQL and NestJS) and transparency/security through blockchain.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Next.js+TailwindCSS)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE["Backend (NestJS)"]:::backend
        subgraph "Backend Modules"
            Admin["Admin Module"]:::backend
            Auth["Auth Module"]:::backend
            Notif["Notifications Module"]:::backend
            Pay["Payments Module"]:::backend
            Price["Pricing Module"]:::backend
            Ship["Shipments Module"]:::backend
            Users["Users Module"]:::backend
            Wallet["Wallet Module"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["PostgreSQL Database"]:::database
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        BC["Smart Contracts (StarkNet/Cairo)"]:::blockchain
    end

    %% External Services
    subgraph "External Services"
        ESNotif["Real-time Notifications (WebSockets)"]:::external
        ESServices["Other Services (GPS/AI Analytics)"]:::external
    end

    %% Connections
    FE -->|"APIcalls"| BE
    BE -->|"CRUD"| DB
    BE -->|"SmartTxns"| BC
    Notif -->|"RealTime"| ESNotif
    BE -->|"Integrations"| ESServices

    %% Click Events
    click FE "https://github.com/codegirlsinc/frieghtflow/tree/main/frontend/"
    click BE "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/"
    click Admin "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/Admin"
    click Auth "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/auth"
    click Notif "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/notifications"
    click Pay "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/payments"
    click Price "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/pricing"
    click Ship "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/shipments"
    click Users "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/users"
    click Wallet "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/wallet"
    click DB "https://github.com/codegirlsinc/frieghtflow/blob/main/backend/src/data-source.ts"
    click BC "https://github.com/codegirlsinc/frieghtflow/tree/main/contract/ffpay/"
    click ESNotif "https://github.com/codegirlsinc/frieghtflow/tree/main/backend/src/notifications/"
    click ESServices "https://github.com/codegirlsinc/frieghtflow/tree/main/frontend/app/services/"

    %% Styles
    classDef frontend fill:#B3D7FF,stroke:#1E90FF,stroke-width:2px;
    classDef backend fill:#C1FFC1,stroke:#228B22,stroke-width:2px;
    classDef database fill:#FFFFCC,stroke:#FFD700,stroke-width:2px;
    classDef blockchain fill:#FFDAB9,stroke:#FF8C00,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#9400D3,stroke-width:2px;
```
