# shaimafikry/transportproject architecture

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

- Interactive diagram: https://gitdiagram.com/shaimafikry/transportproject
- Repository: https://github.com/shaimafikry/transportproject

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Transport Management System”) with:
- A React single-page frontend for managers & workers
- A Node.js/Express backend exposing a REST API
- A PostgreSQL database accessed via Sequelize ORM
- JWT-based authentication and role-based access
- Email notifications via Nodemailer

##### File Structure
- Top-level:
- `.github/` & `.vercel/`: CI/CD + hosting configs
- `backend/`: Express server, route definitions, controllers, config, auth, email logic
- `frontend/`: React app (components, API client, build artifacts)
- Backend patterns:
- allRoute.js registers route endpoints → controllers (`authController.js`, `attendanceCont.js`, etc.)
- `authToken.js` middleware for JWT verification
- `config.js` holds DB & JWT settings
- `sendEmail.js` encapsulates email logic (Nodemailer)
- Frontend patterns:
- `src/api.js`: centralizes HTTP calls to backend
- React Router (`protectedRoutes.jsx`) for navigation & access control
- Component hierarchy under `src/components/` for UI modules (Dashboard, Signin, user/driver/trip management, modals, filters)

##### README for Additional Insights
- Confirms tech stack, data model (Users/Roles, Drivers, Trips, Expenses, Payments), and features (trip tracking, finance calculations, dashboards).
- Mentions future enhancements but core is REST + SPA + relational DB.

a. Main Components
1. Client Browser (Users: Manager, Worker)
2. React SPA (served via Vercel or static host)
3. API Gateway / Node.js Express Server
4. Authentication Layer (JWT middleware)
5. Business Logic / Controllers
6. Sequelize ORM + PostgreSQL Database
7. External SMTP Service (for Nodemailer)
8. CI/CD Pipeline (GitHub Actions → Vercel Deployment)

b. Relationships & Data Flows
- User → React SPA (HTTP/HTTPS)
- React SPA → Express API (`api.js` issues fetch/axios calls)
- Express API → JWT middleware (`authToken.js`) → Controllers
- Controllers → Sequelize → PostgreSQL
- Controllers → `sendEmail.js` → SMTP Service
- GitHub → GitHub Actions (.github/workflows/deploy.yml) → Vercel

c. Architectural Patterns / Design Principles
- Layered Architecture (Presentation → API → Business Logic → Data)
- MVC-style Controllers & Models (Sequelize for ORM)
- Stateless JWT Authentication
- Component-based UI with protected routes
- Configuration-driven (dotenv via `config.js`)
- CI/CD for automated build & deploy

d. Key Technologies
- Frontend: React, React Router, React Bootstrap, xlsx, date-fns
- Backend: Node.js, Express, Sequelize, PostgreSQL, JWT, bcrypt, Nodemailer
- DevOps: GitHub Actions, Vercel

##### Capturing Essential Elements
- Don’t omit the JWT auth layer between API and controllers.
- Role-based access (e.g., annotate the protected-routes component).
- `api.js` module as the single source of truth for HTTP calls.
- Environment/configuration block feeding API and DB credentials.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        Browser["Client Browser"]:::external
        SPA["React SPA"]:::compute
        APIClient["HTTP Client Module\n(api.js)"]:::compute
        Protected["Protected Routes\n(protectedRoutes.jsx)"]:::compute
        Dashboard["Dashboard UI\n(Dashboard.js)"]:::compute
        SignIn["Sign-In UI\n(Signin.js)"]:::compute
        Users["User List\n(users.jsx)"]:::compute
        UserFilter["User Filter\n(userFilter.jsx)"]:::compute
        Drivers["Driver List\n(drivers.jsx)"]:::compute
        DriverProfile["Driver Profile\n(driverProfile.jsx)"]:::compute
        DriverFilter["Driver Filter\n(driverFilter.jsx)"]:::compute
        TripModal["Trip Modal\n(tripModal.jsx)"]:::compute
        ImportTrips["Import Trips\n(import.jsx)"]:::compute
        AttendanceUI["Attendance UI\n(attendance.jsx)"]:::compute
    end

    subgraph "Backend Layer"
        Express["Express API\n(server.js)"]:::compute
        Config["Configuration\n(config.js)"]:::config
        JWT["JWT Middleware\n(authToken.js)"]:::compute
        AllRoute["Route Registration\n(allRoute.js)"]:::compute
        AuthCont["Authentication Controller\n(authController.js)"]:::compute
        AttendCont["Attendance Controller\n(attendanceCont.js)"]:::compute
        Controllers["General Controllers\n(controllers.js)"]:::compute
        ORM["Sequelize ORM"]:::compute
        DB["PostgreSQL DB"]:::db
        Email["Email Service\n(sendEmail.js)"]:::compute
        SMTP["External SMTP Service"]:::external
    end

    subgraph "DevOps CI/CD"
        GitHub["GitHub Repository"]:::cicd
        Actions["GitHub Actions\n(deploy.yml)"]:::cicd
        VercelProj["Vercel Project Config\n(.vercel/project.json)"]:::compute
        VercelFrontCfg["Frontend Vercel Config\n(frontend/.vercel/output/config.json)"]:::compute
        Vercel["Vercel Hosting"]:::external
    end

    %% Frontend to Backend flow
    Browser -->|"loads SPA"| SPA
    SPA -->|"uses api.js"| APIClient
    SPA -->|"protected by"| Protected
    APIClient -->|"HTTP requests"| Express

    %% Backend internal flow
    Express -->|"loads config"| Config
    Express -->|"JWT verification"| JWT
    JWT -->|"routes to"| AllRoute
    AllRoute -->|"calls"| AuthCont
    AllRoute -->|"calls"| AttendCont
    AllRoute -->|"calls"| Controllers
    AuthCont -->|"DB access"| ORM
    AttendCont -->|"DB access"| ORM
    Controllers -->|"DB access"| ORM
    ORM -->|"queries"| DB
    AuthCont -->|"sends email"| Email
    Controllers -->|"sends email"| Email
    Email -->|"SMTP"| SMTP

    %% CI/CD flow
    GitHub -->|"push code"| Actions
    Actions -->|"deploy config"| VercelProj
    VercelProj -->|"build frontend"| VercelFrontCfg
    Actions -->|"deploy to"| Vercel

    %% Click Events
    click SPA "https://github.com/shaimafikry/transportproject/tree/master/frontend/src/"
    click APIClient "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/api.js"
    click Protected "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/protectedRoutes.jsx"
    click Dashboard "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/Dashboard.js"
    click SignIn "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/Signin.js"
    click Users "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/users.jsx"
    click UserFilter "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/userFilter.jsx"
    click Drivers "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/drivers.jsx"
    click DriverProfile "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/driverProfile.jsx"
    click DriverFilter "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/driverFilter.jsx"
    click TripModal "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/tripModal.jsx"
    click ImportTrips "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/import.jsx"
    click AttendanceUI "https://github.com/shaimafikry/transportproject/blob/master/frontend/src/components/attendance.jsx"
    click Express "https://github.com/shaimafikry/transportproject/blob/master/backend/server.js"
    click AllRoute "https://github.com/shaimafikry/transportproject/blob/master/backend/allRoute.js"
    click AuthCont "https://github.com/shaimafikry/transportproject/blob/master/backend/authController.js"
    click AttendCont "https://github.com/shaimafikry/transportproject/blob/master/backend/attendanceCont.js"
    click Controllers "https://github.com/shaimafikry/transportproject/blob/master/backend/controllers.js"
    click JWT "https://github.com/shaimafikry/transportproject/blob/master/backend/authToken.js"
    click Config "https://github.com/shaimafikry/transportproject/blob/master/backend/config.js"
    click Email "https://github.com/shaimafikry/transportproject/blob/master/backend/sendEmail.js"
    click Actions "https://github.com/shaimafikry/transportproject/blob/master/.github/workflows/deploy.yml"
    click VercelProj "https://github.com/shaimafikry/transportproject/blob/master/.vercel/project.json"
    click VercelFrontCfg "https://github.com/shaimafikry/transportproject/blob/master/frontend/.vercel/output/config.json"

    %% Styles
    classDef compute fill:#cce5ff,stroke:#0366d6;
    classDef db fill:#d4edda,stroke:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d;
    classDef cicd fill:#fff3cd,stroke:#856404;
    classDef config fill:#f8d7da,stroke:#721c24;
```
