# aminebenz0/marwane-vercel architecture

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

- Interactive diagram: https://gitdiagram.com/aminebenz0/marwane-vercel
- Repository: https://github.com/aminebenz0/marwane-vercel

## Overview

1. **Overall shape**  
This repo is a two-tier internal accounting system: a **FastAPI backend** exposes a JSON API, and a **React/Vite frontend** consumes it. The core data store is **PostgreSQL**, managed through **SQLAlchemy** and **Alembic** migrations.

2. **Backend entrypoint and API boundary**  
The backend lives under `backend/app`. `app/main.py` is the application bootstrap, while `app/routers/*` defines the public API surface by domain: auth, users, clients, suppliers, products, transactions, cash, payments, bank accounts, letters of credit, cessions, productions, transformations, charges, buildings, and tasks. This router layer is the main boundary between HTTP requests and business data.

3. **Backend domain model and persistence**  
`backend/app/models/*` contains the persisted business entities. The model set shows the accounting domain clearly: users, clients, fournisseurs, produits, transactions, caisse, paiements, comptes bancaires, lettres de crédit, productions, transformations, charges, and audit records. The schema layer in `app/schemas/*` mirrors these models for request/response validation with Pydantic.

4. **Security and access control**  
Authentication is JWT-based, with access and refresh tokens handled in `app/routers/auth.py` and shared security helpers in `app/utils/security.py`. The backend also includes dependency helpers and rate limiting utilities, which indicates that sensitive endpoints are protected centrally rather than per-page. The repo README and tests suggest role-aware access and admin-oriented operations.

5. **Cross-cutting backend concerns**  
`backend/app/middleware/logging_middleware.py` and `app/config/logging_config.py` handle structured request/action logging. This is important because the system is designed for traceability, not just CRUD. There is also a dedicated `audit` model plus audit-related migrations and tests, showing that modification history is treated as a first-class concern.

6. **Database evolution and integrity**  
Alembic migrations are extensive and domain-driven, not just initial schema setup. The migration history includes business constraints, performance indexes, audit triggers, payment tables, cash balance materialized views, transaction flattening, and later feature additions like product flags and credit-letter support. That tells you the database is a central enforcement point for integrity and reporting, not merely storage.

7. **Frontend application structure**  
The frontend is organized by feature pages under `frontend/src/pages/*` with reusable UI components under `frontend/src/components/*`. There are dedicated screens and flows for dashboard, login, transactions, cash, clients, suppliers, products, payments, productions, letters of credit, charges, bank accounts, and tasks. The structure implies a navigation-heavy internal admin app rather than a public consumer site.

8. **Frontend data flow and state**  
Frontend API access is centralized in `frontend/src/services/*`, while global client state is managed with **Zustand** in `src/store/*`. Routing and route protection are handled with `ProtectedRoute` and `AdminProtectedRoute`, so authentication gates sit at the UI boundary as well as in the backend. Notification and error handling are also cross-cutting concerns through provider and boundary components.

9. **UI behavior and presentation layer**  
The UI uses **MUI** and includes reusable data-heavy components like tables/grids, filter panels, status badges, cards, and modal forms. The presence of `FinancialInsights`, export helpers for Excel/PDF, and mobile card lists suggests the app supports both operational entry and management/reporting views. This is a dashboard-style front end with responsive fallbacks, not a simple form app.

10. **Infrastructure, deployment, and quality gates**  
The repo is built for containerized deployment with Dockerfiles for both backend and frontend, plus `docker-compose.yml` for local PostgreSQL-backed development. There are deployment scripts for production/Azure and a Vercel config, indicating multiple deployment targets. Testing is significant: backend unit/integration/security tests, OWASP-focused checks, audit-trigger tests, and load testing with Locust, which reinforces that correctness and security are architectural priorities.

11. **Operational support scripts**  
Several scripts exist for admin bootstrapping, DB checks, fixing inconsistencies, generating security reports, and verifying indexes. These are not core runtime pieces, but they show the system is intended to be operated with explicit maintenance tooling around data integrity and security.

12. **Main end-to-end flow**  
A typical request flows from the React page → service module → FastAPI router → schema validation → SQLAlchemy model → PostgreSQL, with auth/dependency checks and logging/audit hooks along the way. The reverse flow returns validated domain data to the UI, where reusable components render lists, forms, status indicators, and dashboard metrics.

Main entry points: [`backend/app/routers`](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/routers) (API routers), [`backend/app/models`](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/models) (Domain models), [`frontend/src/pages`](https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/pages) (Feature pages), [`backend/app/main.py`](https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/main.py) (API entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_api_entry["API entry<br/>fastapi bootstrap<br/>[main.py]"]
  node_api_routes["API routers<br/>http routes"]
  node_auth["Auth<br/>jwt security<br/>[auth.py]"]
  node_core_models[("Domain models<br/>sqlalchemy models")]
  node_schemas["Schemas"]
  node_security_utils["Security utils<br/>deps and jwt<br/>[security.py]"]
  node_logging["Logging<br/>middleware config"]
end

subgraph group_frontend["Frontend"]
  node_frontend_entry["UI entry<br/>react bootstrap<br/>[App.jsx]"]
  node_pages["Feature pages<br/>react screens"]
  node_ui_components["UI components<br/>shared widgets"]
  node_api_client["API client<br/>service layer"]
  node_store["Client store<br/>zustand state"]
  node_route_guards["Route guards<br/>ui access control<br/>[ProtectedRoute.jsx]"]
end

subgraph group_infra["Infra & Quality"]
  node_db[("PostgreSQL<br/>relational store")]
  node_migrations["Migrations<br/>alembic history"]
  node_tests["Tests<br/>backend quality"]
  node_deploy["Deploy tooling<br/>container and scripts<br/>[docker-compose.yml]"]
  node_ops_scripts["Ops scripts<br/>maintenance tools"]
end

node_api_entry -->|"mounts"| node_api_routes
node_api_routes -->|"includes"| node_auth
node_api_routes -->|"serves"| node_core_models
node_api_routes -->|"validates with"| node_schemas
node_auth -->|"uses"| node_security_utils
node_core_models -->|"persists to"| node_db
node_schemas -.->|"mirrors"| node_core_models
node_migrations -->|"evolves"| node_db
node_logging -.->|"wraps"| node_api_entry
node_frontend_entry -->|"routes to"| node_pages
node_pages -->|"composes"| node_ui_components
node_pages -->|"fetches via"| node_api_client
node_api_client -.->|"updates"| node_store
node_route_guards -->|"reads"| node_store
node_route_guards -->|"protects"| node_frontend_entry
node_tests -.->|"verifies"| node_core_models
node_tests -.->|"verifies"| node_auth
node_deploy -->|"runs"| node_api_entry
node_deploy -->|"builds"| node_frontend_entry
node_ops_scripts -.->|"maintains"| node_db
node_ops_scripts -.->|"checks"| node_security_utils

click node_api_entry "https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/routers"
click node_auth "https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/routers/auth.py"
click node_core_models "https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/models"
click node_schemas "https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/schemas"
click node_security_utils "https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/utils/security.py"
click node_logging "https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/middleware/logging_middleware.py"
click node_migrations "https://github.com/aminebenz0/marwane-vercel/tree/main/backend/alembic/versions"
click node_frontend_entry "https://github.com/aminebenz0/marwane-vercel/blob/main/frontend/src/App.jsx"
click node_pages "https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/pages"
click node_ui_components "https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/components"
click node_api_client "https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/services"
click node_store "https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/store"
click node_route_guards "https://github.com/aminebenz0/marwane-vercel/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_tests "https://github.com/aminebenz0/marwane-vercel/tree/main/backend/tests"
click node_deploy "https://github.com/aminebenz0/marwane-vercel/blob/main/docker-compose.yml"
click node_ops_scripts "https://github.com/aminebenz0/marwane-vercel/tree/main/backend/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_entry,node_api_routes,node_auth,node_core_models,node_schemas,node_security_utils,node_logging toneBlue
class node_frontend_entry,node_pages,node_ui_components,node_api_client,node_store,node_route_guards toneAmber
class node_db,node_migrations,node_tests,node_deploy,node_ops_scripts toneMint
```

## Components

### Backend

FastAPI API, domain models, persistence, and cross-cutting security/logging.

- [API entry](https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/main.py): fastapi bootstrap · Application startup and ASGI wiring for the backend API. · `backend/app/main.py`
- [API routers](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/routers): http routes · Domain router layer exposing the public JSON API. · `backend/app/routers`
- [Auth](https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/routers/auth.py): jwt security · Login, token handling, and protected access control. · `backend/app/routers/auth.py`
- [Domain models](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/models): sqlalchemy models · Persisted accounting entities and records. · `backend/app/models`
- [Schemas](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/app/schemas): pydantic schemas · Request and response validation models mirroring the domain. · `backend/app/schemas`
- [Security utils](https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/utils/security.py): deps and jwt · Shared dependencies, JWT helpers, and rate limiting. · `backend/app/utils/security.py`
- [Logging](https://github.com/aminebenz0/marwane-vercel/blob/main/backend/app/middleware/logging_middleware.py): middleware config · Structured request and action logging across the backend. · `backend/app/middleware/logging_middleware.py`

### Frontend

React/Vite admin UI, feature pages, shared components, and client state.

- [UI entry](https://github.com/aminebenz0/marwane-vercel/blob/main/frontend/src/App.jsx): react bootstrap · Frontend application bootstrap and route wiring. · `frontend/src/App.jsx`
- [Feature pages](https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/pages): react screens · Dashboard and domain screens for transactions, cash, clients, suppliers, products, payments, production, letters of credit, charges, bank accounts, and tasks. · `frontend/src/pages`
- [UI components](https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/components): shared widgets · Reusable tables, filters, forms, badges, cards, and layout pieces. · `frontend/src/components`
- [API client](https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/services): service layer · Centralized HTTP access from the frontend to backend endpoints. · `frontend/src/services`
- [Client store](https://github.com/aminebenz0/marwane-vercel/tree/main/frontend/src/store): zustand state · Global auth and notification state on the client. · `frontend/src/store`
- [Route guards](https://github.com/aminebenz0/marwane-vercel/blob/main/frontend/src/components/ProtectedRoute.jsx): ui access control · Protected and admin-only navigation boundaries in the UI. · `frontend/src/components/ProtectedRoute.jsx`

### Infra & Quality

Database migrations, deployment, scripts, and automated tests.

- **PostgreSQL**: relational store · Primary data store for accounting, reporting, and audit history.
- [Migrations](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/alembic/versions): alembic history · Domain-driven schema evolution, constraints, indexes, and views. · `backend/alembic/versions`
- [Tests](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/tests): backend quality · Security, auth, business constraint, audit trigger, and load tests. · `backend/tests`
- [Deploy tooling](https://github.com/aminebenz0/marwane-vercel/blob/main/docker-compose.yml): container and scripts · Docker, compose, deployment scripts, and environment startup helpers. · `docker-compose.yml`
- [Ops scripts](https://github.com/aminebenz0/marwane-vercel/tree/main/backend/scripts): maintenance tools · Administrative helpers for users, checks, fixes, and security reports. · `backend/scripts`

## Connections

- API entry → API routers: mounts · Startup wires routers into the API.
- API routers → Auth: includes · Authentication is a first-class route boundary.
- API routers → Domain models: serves · Routers operate on the persisted domain.
- API routers → Schemas: validates with · Request and response payloads use Pydantic schemas.
- Auth → Security utils: uses · JWT and dependency helpers centralize protection.
- Domain models → PostgreSQL: persists to · SQLAlchemy models map to PostgreSQL tables.
- Schemas → Domain models: mirrors · Schemas reflect domain entities for API I/O.
- Migrations → PostgreSQL: evolves · Alembic changes the database schema and reporting structures.
- Logging → API entry: wraps · Request logging is applied at the backend boundary.
- UI entry → Feature pages: routes to · The app renders feature screens by route.
- Feature pages → UI components: composes · Pages are built from reusable presentation and form widgets.
- Feature pages → API client: fetches via · Screens call centralized services for backend data.
- API client → Client store: updates · Client state and auth status are kept in shared stores.
- Route guards → Client store: reads · Navigation guards depend on auth state.
- Route guards → UI entry: protects · Authenticated and admin flows are gated at the UI boundary.
- Tests → Domain models: verifies · Tests cover business rules and persistence behavior.
- Tests → Auth: verifies · Security and authentication are explicitly tested.
- Deploy tooling → API entry: runs · Container and process scripts start the backend service.
- Deploy tooling → UI entry: builds · Deployment tooling also packages the frontend app.
- Ops scripts → PostgreSQL: maintains · Operational scripts inspect and repair data integrity.
- Ops scripts → Security utils: checks · Some scripts focus on security verification and reporting.
