# justlugoo/leadsmanager architecture

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

- Interactive diagram: https://gitdiagram.com/justlugoo/leadsmanager
- Repository: https://github.com/justlugoo/leadsmanager

## Overview

##### Project type and purpose
- This is a full-stack CRM-style application (“Leads Manager”) with:
- A RESTful API backend (FastAPI, SQLAlchemy, Pydantic)
- A modern SPA frontend (React + TypeScript + Vite)
- JWT-based authentication and role-based protected routes
- A relational database (SQLite in dev, pluggable to Postgres/MySQL)

##### File structure
- Top-level
- `.github/workflows/deploy-gcp.yml` – CI/CD pipeline
- `docker-compose.yml` – multi-container orchestration (frontend + backend)
- `Makefile` – common tasks
- Backend (`backend-lm/`)
- `src/main.py` – application entry point
- `src/routers/` – API endpoints grouped by domain (users, leads)
- `src/services/` – business logic layer
- `src/models/` – SQLAlchemy ORM definitions
- `src/schemas/` – Pydantic request/response models
- `src/database/` – DB connection and session management
- `utils/security.py` – JWT generation/verification, password hashing
- Frontend (`frontend-lm/`)
- `src/App.tsx` + `src/routes/` – route configuration (React Router)
- `src/pages/` – top-level pages (Auth, Dashboard, Leads, Profile)
- `src/components/` – reusable UI, layout, auth, leads modules
- `src/services/api.ts` – Axios HTTP client
- `src/services/leads/` – API wrappers for leads endpoints
- `src/context/UserContext.tsx` + `src/hooks/useAuth.ts` – authentication state

##### README for additional insights
- Confirms layered architecture: routers → services → models/schemas → database
- Lists key endpoints and authentication flows
- Describes frontend features: protected routes, JWT in localStorage
- Technology stack: FastAPI, React, Tailwind, Vite, Axios, SQLAlchemy, Pydantic

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Frontend Layer
  subgraph "Frontend Layer"
    Browser["Client Browser (React SPA)"]:::ui
    subgraph "Frontend Server"
      Vite["Vite Dev Server"]:::ui
      Nginx["Nginx (Prod)"]:::ui
    end
    App["SPA Entry Point (App.tsx)"]:::ui
    Routes["Route Config (index.ts)"]:::ui
    Protected["ProtectedRoute Component"]:::ui
    Login["Login Page"]:::ui
    Register["Register Page"]:::ui
    Dashboard["Dashboard Page"]:::ui
    LeadsList["Leads List Page"]:::ui
    LeadDetail["Lead Detail Page"]:::ui
    LeadForm["Lead Form Page"]:::ui
    Profile["Profile Page"]:::ui
    UI["UI Components"]:::ui
    AuthLayout["Auth/Layout Components"]:::ui
    APIClient["Axios HTTP Client"]:::ui
    LeadsServiceFE["Leads API Wrapper"]:::ui
    UserContext["UserContext"]:::ui
    UseAuth["useAuth Hook"]:::ui
  end

  %% Backend Layer
  subgraph "Backend Layer"
    APIGateway["FastAPI App (main.py)"]:::api
    subgraph "API Routers"
      AuthRouter["Auth/User Routes"]:::api
      UsersRouter["User Routes"]:::api
      LeadsRouter["Leads Routes"]:::api
    end
    subgraph "Services Layer"
      AuthService["Auth Services"]:::service
      UserService["User Services"]:::service
      LeadsServiceBE["Leads Services"]:::service
    end
    subgraph "Data Layer"
      Models["ORM Models"]:::data
      Schemas["Pydantic Schemas"]:::data
      DB["Database & Session"]:::data
      AuthUtil["Auth Module (JWT & Hashing)"]:::service
    end
  end

  %% Infrastructure & DevOps
  subgraph "Infrastructure & DevOps"
    DockerCompose["Docker Compose"]:::devops
    BackendDocker["Backend Dockerfile"]:::devops
    FrontendDocker["Frontend Dockerfile"]:::devops
    CICD["GitHub Actions CI/CD"]:::devops
  end

  %% Connections - Frontend
  Browser --> Vite
  Browser --> Nginx
  Vite --> App
  Nginx --> App
  App --> Routes
  Routes --> Protected
  Routes --> Login
  Routes --> Register
  Routes --> Dashboard
  Routes --> LeadsList
  Routes --> LeadDetail
  Routes --> LeadForm
  Routes --> Profile
  App --> UI
  App --> AuthLayout
  Protected --> APIClient
  App --> UserContext
  App --> UseAuth
  APIClient --> APIGateway
  LeadsServiceFE --> APIClient

  %% Connections - Backend
  APIGateway --> AuthRouter
  APIGateway --> UsersRouter
  APIGateway --> LeadsRouter
  AuthRouter --> AuthService
  UsersRouter --> UserService
  LeadsRouter --> LeadsServiceBE
  AuthService --> AuthUtil
  AuthService --> DB
  UserService --> DB
  LeadsServiceBE --> DB
  AuthService --> Schemas
  UserService --> Schemas
  LeadsServiceBE --> Schemas
  Models --> DB
  Schemas --> DB

  %% DevOps Connections
  CICD --> DockerCompose
  DockerCompose --> Vite
  DockerCompose --> APIGateway
  DockerCompose --> DB

  %% Click Events - Frontend
  click Browser "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/main.tsx"
  click Vite "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/vite.config.ts"
  click Nginx "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/nginx.conf"
  click App "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/App.tsx"
  click Routes "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/routes/index.ts"
  click Protected "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/components/ProtectedRoute.tsx"
  click Login "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/pages/auth/Login.tsx"
  click Register "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/pages/auth/Register.tsx"
  click Dashboard "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/pages/dashboard/Dashboard.tsx"
  click LeadsList "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/pages/leads/LeadsList.tsx"
  click LeadDetail "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/pages/leads/LeadDetail.tsx"
  click LeadForm "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/pages/leads/LeadForm.tsx"
  click Profile "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/pages/profile/Profile.tsx"
  click UI "https://github.com/justlugoo/leadsmanager/tree/main/frontend-lm/src/components/ui"
  click AuthLayout "https://github.com/justlugoo/leadsmanager/tree/main/frontend-lm/src/components/auth"
  click APIClient "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/services/api.ts"
  click LeadsServiceFE "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/services/leads/leads_service.ts"
  click UserContext "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/context/UserContext.tsx"
  click UseAuth "https://github.com/justlugoo/leadsmanager/blob/main/frontend-lm/src/hooks/useAuth.ts"

  %% Click Events - Backend
  click APIGateway "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/main.py"
  click AuthRouter "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/routers/users/auth_users.py"
  click UsersRouter "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/routers/users/users.py"
  click LeadsRouter "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/routers/leads/leads.py"
  click AuthService "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/services/users/auth_users_services.py"
  click UserService "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/services/users/users_services.py"
  click LeadsServiceBE "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/services/leads/leads_services.py"
  click Models "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/models/users/user_model.py"
  click Models "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/models/leads/lead_model.py"
  click Schemas "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/schemas/users/auth_schema.py"
  click Schemas "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/schemas/users/user_schema.py"
  click Schemas "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/schemas/leads/lead_schema.py"
  click DB "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/database/database.py"
  click AuthUtil "https://github.com/justlugoo/leadsmanager/blob/main/backend-lm/src/utils/security.py"

  %% Click Events - DevOps
  click DockerCompose "https://github.com/justlugoo/leadsmanager/blob/main/docker-compose.yml"
  click BackendDocker "https://github.com/justlugoo/leadsmanager/tree/main/backend-lm/Dockerfile"
  click FrontendDocker "https://github.com/justlugoo/leadsmanager/tree/main/frontend-lm/Dockerfile"
  click CICD "https://github.com/justlugoo/leadsmanager/blob/main/.github/workflows/deploy-gcp.yml"

  %% Styles
  classDef ui fill:#CCE5FF,stroke:#333,stroke-width:1px
  classDef api fill:#CCFFCC,stroke:#333,stroke-width:1px
  classDef service fill:#FFE5CC,stroke:#333,stroke-width:1px
  classDef data fill:#E0E0E0,stroke:#333,stroke-width:1px
  classDef devops fill:#F0D9FF,stroke:#333,stroke-width:1px
```
