How aminebenz0/marwane-vercel works
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: routers API routers · models Domain models · pages Feature pages · main.py API entry
Components 18
Backend
FastAPI API, domain models, persistence, and cross-cutting security/logging.
- API entry · Application startup and ASGI wiring for the backend API.
backend/app/main.py - API routers · Domain router layer exposing the public JSON API.
backend/app/routers - Auth · Login, token handling, and protected access control.
backend/app/routers/auth.py - Domain models · Persisted accounting entities and records.
backend/app/models - Schemas · Request and response validation models mirroring the domain.
backend/app/schemas - Security utils · Shared dependencies, JWT helpers, and rate limiting.
backend/app/utils/security.py - Logging · 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 · Frontend application bootstrap and route wiring.
frontend/src/App.jsx - Feature pages · 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 · Reusable tables, filters, forms, badges, cards, and layout pieces.
frontend/src/components - API client · Centralized HTTP access from the frontend to backend endpoints.
frontend/src/services - Client store · Global auth and notification state on the client.
frontend/src/store - Route guards · Protected and admin-only navigation boundaries in the UI.
frontend/src/components/ProtectedRoute.jsx
Infra & Quality
Database migrations, deployment, scripts, and automated tests.
- PostgreSQL · Primary data store for accounting, reporting, and audit history.
- Migrations · Domain-driven schema evolution, constraints, indexes, and views.
backend/alembic/versions - Tests · Security, auth, business constraint, audit trigger, and load tests.
backend/tests - Deploy tooling · Docker, compose, deployment scripts, and environment startup helpers.
docker-compose.yml - Ops scripts · Administrative helpers for users, checks, fixes, and security reports.
backend/scripts
Connections 21
- 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.