# arnaud-dev04/pharmagestion architecture

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

- Interactive diagram: https://gitdiagram.com/arnaud-dev04/pharmagestion
- Repository: https://github.com/arnaud-dev04/pharmagestion

## Overview

1. **Overall shape**
   This is a pharmacy management monorepo with two primary runtime surfaces: a **Python/FastAPI backend** and a **Flutter client**. The same product is packaged for **desktop, web, and mobile**, and there is also a **serverless/Vercel deployment path** with prebuilt web assets and API entrypoints.

2. **Backend as the system of record**
   The backend lives under `backend/` and is the authoritative business layer. `backend/main.py` starts the FastAPI app, while `backend/app/` is organized by concern: `routes/` for HTTP endpoints, `services/` for business logic, `models/` for SQLAlchemy entities, `schemas/` for Pydantic validation, and `database/` for persistence setup.

3. **Core domain boundaries**
   The backend domain is centered on pharmacy operations:
   - inventory/stock (`medicine`, `batch`, `stock_movement`)
   - suppliers and customers
   - restocking and purchasing flows
   - POS and sales (`pos_sale`, `sales`)
   - pricing (`medicine_pricing`)
   - users, settings, and dashboard/reporting
   These are separated into dedicated routes and services, which is the main structure to reflect in an architecture diagram.

4. **Persistence and dual-database design**
   The README explicitly describes **SQLite for offline/local mode** and **MySQL for online mode**. The presence of `sync_queue` and `sync_log` models, plus the `sync/` package, shows that local operations are expected to be buffered and later synchronized. Database migrations are handled with **Alembic**, including a pricing-related migration.

5. **Service layer orchestration**
   The backend service layer is where business workflows are assembled before reaching the database. Notable service modules include `pos_service`, `sales_service`, `restock_service`, `medicine_service`, `supplier_service`, `customer_service`, `dashboard_service`, `report_service`, `pdf_service`, and `medicine_pricing_service`. This is the boundary between HTTP/API concerns and domain operations.

6. **Cross-cutting backend concerns**
   Several modules implement system-level behavior rather than business entities:
   - `auth/` for JWT/auth dependencies
   - `core/config.py` for environment-driven configuration
   - `core/license.py` for license enforcement
   - `utils/security.py` for password/token/security helpers
   - `utils/i18n.py` plus `app/i18n/messages_*.json` for backend localization
   These are shared concerns used by multiple routes/services.

7. **API surface by feature**
   The route layer is feature-oriented rather than purely REST-generic. There are endpoints for `auth`, `users`, `admin`, `license`, `config`, `dashboard`, `metrics`, `stock`, `sales`, `pos`, `restock`, `suppliers`, `customers`, `reports`, `settings`, `medicine_pricing`, and `sync`. For a diagram, these should appear as the external API boundary exposing the backend capabilities.

8. **Frontend application architecture**
   The Flutter app is in `frontend1/` and is the interactive client for all pharmacy workflows. It follows a typical Flutter layering:
   - `core/` for constants, theme, styles
   - `models/` for client-side data shapes
   - `services/` for API calls
   - `providers/` for state management
   - `screens/` and `widgets/` for presentation
   The client is explicitly multi-platform: Android, Windows, and Web.

9. **Frontend state and API flow**
   The client uses **Provider** for state management and a separate `services/` layer for HTTP integration. `api_service.dart` is the lower-level network boundary, and feature services such as `auth_service`, `stock_service`, `sales_service`, `restock_service`, `reports_service`, `supplier_service`, and `user_service` sit above it. Authentication state, cart state, theme, language, and license status are all managed on the client side.

10. **Major UI subsystems**
    The UI is organized around the same business domains as the backend:
    - authentication/login
    - main layout with sidebar/header
    - dashboard with charts and KPIs
    - POS/cart/payment flows
    - stock and medicine forms
    - sales history
    - restock management
    - suppliers, users, reports, and settings
    This tight alignment between screens and backend features makes the client a thin domain-facing layer over the API.

11. **Localization and UX features**
    Both backend and frontend support French/English, but the frontend carries the user-facing localization system via `l10n/` and language provider state. The client also includes theme toggling and secure token storage, which are important operational boundaries in the architecture diagram.

12. **Reporting and export pipeline**
    Reporting is a first-class subsystem: the backend includes PDF/Excel generation support (`pdf_service`, `report_service`, and related dependencies), and the frontend exposes report screens. These flows likely traverse from UI → API → service layer → generated document/file response.

13. **Deployment and packaging boundaries**
    There are separate deployment artifacts for different targets:
    - root and `deploy_vercel/` contain Vercel-oriented API wrappers and prebuilt Flutter web output
    - `frontend_build/` and `deploy_vercel/frontend_build/` are compiled web assets
    - `.bat` scripts and `render.yaml` suggest Windows and cloud deployment support
    This indicates the repo is not just source code; it also contains packaging output and environment-specific entrypoints.

14. **What to emphasize in a diagram**
    The most important architecture boundaries are:
    **Flutter client** → **FastAPI routes** → **service layer** → **database/models**
    with a side path for **offline sync** and **license/auth/security** as cross-cutting concerns. The two-database offline/online model and the feature split around stock, POS, sales, restocking, and reporting are the key structural elements.

Main entry points: [`backend/app/services`](https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/services) (Domain services), [`frontend1/lib/main.dart`](https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend1/lib/main.dart) (Flutter app), [`backend/app/routes`](https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/routes) (API routes), [`backend/main.py`](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/main.py) (App start)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["App start<br/>FastAPI entrypoint<br/>[main.py]"]
  node_backend_routes["API routes<br/>HTTP boundary"]
  node_backend_services["Domain services<br/>business orchestration"]
  node_backend_models[("Data models<br/>SQLAlchemy entities")]
  node_backend_schemas["Schemas<br/>validation layer"]
  node_backend_database[("Database core<br/>persistence setup<br/>[core.py]")]
  node_backend_sync["Sync manager<br/>offline sync<br/>[sync_manager.py]"]
  node_backend_auth["Auth deps<br/>security boundary<br/>[dependencies.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_license["License<br/>policy check<br/>[license.py]"]
  node_backend_i18n["Messages<br/>localization<br/>[messages_en.json]"]
  node_backend_security["Security utils<br/>crypto helpers<br/>[security.py]"]
end

subgraph group_frontend["Flutter client"]
  node_frontend_main["Flutter app<br/>cross-platform entry<br/>[main.dart]"]
  node_frontend_providers["State providers<br/>UI state"]
  node_frontend_api["API client<br/>HTTP boundary<br/>[api_service.dart]"]
  node_frontend_screens["Screens<br/>presentation layer"]
  node_frontend_widgets["Widgets<br/>UI components"]
  node_frontend_l10n["Localizations<br/>UI localization"]
end

subgraph group_deploy["Deployment"]
  node_frontend_web["Web build<br/>compiled assets<br/>[index.html]"]
  node_deploy_api["Vercel API<br/>serverless entry<br/>[index.py]"]
  node_deploy_web["Deployed web<br/>static bundle<br/>[index.html]"]
end

node_backend_main -->|"registers"| node_backend_routes
node_backend_routes -->|"calls"| node_backend_services
node_backend_services -->|"persists"| node_backend_models
node_backend_services -->|"validates"| node_backend_schemas
node_backend_main -->|"initializes"| node_backend_database
node_backend_main -->|"enables"| node_backend_sync
node_backend_routes -->|"protects"| node_backend_auth
node_backend_services -->|"reads"| node_backend_config
node_backend_services -->|"checks"| node_backend_license
node_backend_routes -.->|"messages"| node_backend_i18n
node_backend_auth -->|"uses"| node_backend_security
node_backend_sync -->|"tracks"| node_backend_models
node_frontend_main -->|"bootstraps"| node_frontend_providers
node_frontend_main -->|"connects"| node_frontend_api
node_frontend_main -->|"navigates"| node_frontend_screens
node_frontend_screens -->|"composes"| node_frontend_widgets
node_frontend_providers -->|"invokes"| node_frontend_api
node_frontend_screens -->|"consumes"| node_frontend_providers
node_frontend_main -->|"localizes"| node_frontend_l10n
node_frontend_api -->|"requests"| node_backend_routes
node_frontend_web -.->|"packaged as"| node_deploy_web
node_deploy_api -->|"wraps"| node_backend_main
node_deploy_web -->|"serves"| node_frontend_main

click node_backend_main "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/main.py"
click node_backend_routes "https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/routes"
click node_backend_services "https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/services"
click node_backend_models "https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/models"
click node_backend_schemas "https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/schemas"
click node_backend_database "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/database/core.py"
click node_backend_sync "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/sync/sync_manager.py"
click node_backend_auth "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/auth/dependencies.py"
click node_backend_config "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/core/config.py"
click node_backend_license "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/core/license.py"
click node_backend_i18n "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/i18n/messages_en.json"
click node_backend_security "https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/utils/security.py"
click node_frontend_main "https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend1/lib/main.dart"
click node_frontend_providers "https://github.com/arnaud-dev04/pharmagestion/tree/main/frontend1/lib/providers"
click node_frontend_api "https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend1/lib/services/api_service.dart"
click node_frontend_screens "https://github.com/arnaud-dev04/pharmagestion/tree/main/frontend1/lib/screens"
click node_frontend_widgets "https://github.com/arnaud-dev04/pharmagestion/tree/main/frontend1/lib/widgets"
click node_frontend_l10n "https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend1/lib/l10n/app_localizations.dart"
click node_frontend_web "https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend_build/index.html"
click node_deploy_api "https://github.com/arnaud-dev04/pharmagestion/blob/main/deploy_vercel/api/index.py"
click node_deploy_web "https://github.com/arnaud-dev04/pharmagestion/blob/main/deploy_vercel/frontend_build/index.html"

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_backend_main,node_backend_routes,node_backend_services,node_backend_models,node_backend_schemas,node_backend_database,node_backend_sync,node_backend_auth,node_backend_config,node_backend_license,node_backend_i18n,node_backend_security toneBlue
class node_frontend_main,node_frontend_providers,node_frontend_api,node_frontend_screens,node_frontend_widgets,node_frontend_l10n toneAmber
class node_frontend_web,node_deploy_api,node_deploy_web toneMint
```

## Components

### Backend

FastAPI system of record with domain routes, services, models, sync, and persistence.

- [App start](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/main.py): FastAPI entrypoint · Bootstraps the backend application and wires the API surface. · `backend/main.py`
- [API routes](https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/routes): HTTP boundary · Feature-oriented endpoints for auth, stock, sales, POS, reports, sync, and admin. · `backend/app/routes`
- [Domain services](https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/services): business orchestration · Coordinates pharmacy workflows before persistence. · `backend/app/services`
- [Data models](https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/models): SQLAlchemy entities · Core persistence model set for inventory, sales, people, pricing, and sync state. · `backend/app/models`
- [Schemas](https://github.com/arnaud-dev04/pharmagestion/tree/main/backend/app/schemas): validation layer · Pydantic request/response contracts used by the API. · `backend/app/schemas`
- [Database core](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/database/core.py): persistence setup · Database wiring and engine/session configuration. · `backend/app/database/core.py`
- [Sync manager](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/sync/sync_manager.py): offline sync · Buffers and reconciles local operations for later synchronization. · `backend/app/sync/sync_manager.py`
- [Auth deps](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/auth/dependencies.py): security boundary · JWT/auth dependencies shared by protected backend routes. · `backend/app/auth/dependencies.py`
- [Config](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/core/config.py): runtime config · Environment-driven backend settings and mode selection. · `backend/app/core/config.py`
- [License](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/core/license.py): policy check · Backend license enforcement and entitlement logic. · `backend/app/core/license.py`
- [Messages](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/i18n/messages_en.json): localization · Backend French/English message catalogs and helpers. · `backend/app/i18n/messages_en.json`
- [Security utils](https://github.com/arnaud-dev04/pharmagestion/blob/main/backend/app/utils/security.py): crypto helpers · Password, token, and security helper functions. · `backend/app/utils/security.py`

### Flutter client

Cross-platform UI with state, services, screens, and shared widgets.

- [Flutter app](https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend1/lib/main.dart): cross-platform entry · Main Flutter application entrypoint for desktop, web, and mobile. · `frontend1/lib/main.dart`
- [State providers](https://github.com/arnaud-dev04/pharmagestion/tree/main/frontend1/lib/providers): UI state · Provider-based state for auth, cart, theme, language, and license. · `frontend1/lib/providers`
- [API client](https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend1/lib/services/api_service.dart): HTTP boundary · Network layer and feature services that call the backend API. · `frontend1/lib/services/api_service.dart`
- [Screens](https://github.com/arnaud-dev04/pharmagestion/tree/main/frontend1/lib/screens): presentation layer · Primary UI surfaces for login, dashboard, POS, stock, sales, restock, reports, settings, and users. · `frontend1/lib/screens`
- [Widgets](https://github.com/arnaud-dev04/pharmagestion/tree/main/frontend1/lib/widgets): UI components · Reusable layout, dashboard, POS, stock, and form components. · `frontend1/lib/widgets`
- [Localizations](https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend1/lib/l10n/app_localizations.dart): UI localization · Generated app translations for English and French. · `frontend1/lib/l10n/app_localizations.dart`

### Deployment

Vercel and packaged web assets for alternate runtime surfaces.

- [Web build](https://github.com/arnaud-dev04/pharmagestion/blob/main/frontend_build/index.html): compiled assets · Compiled Flutter web output packaged for browser deployment. · `frontend_build/index.html`
- [Vercel API](https://github.com/arnaud-dev04/pharmagestion/blob/main/deploy_vercel/api/index.py): serverless entry · Vercel entrypoint wrapping the backend for deployment. · `deploy_vercel/api/index.py`
- [Deployed web](https://github.com/arnaud-dev04/pharmagestion/blob/main/deploy_vercel/frontend_build/index.html): static bundle · Prebuilt web assets shipped with the Vercel deployment path. · `deploy_vercel/frontend_build/index.html`

## Connections

- App start → API routes: registers · Main app mounts the feature API routes.
- API routes → Domain services: calls · Routes delegate work to domain services.
- Domain services → Data models: persists · Services read and write the domain entities.
- Domain services → Schemas: validates · Services and routes exchange structured payloads.
- App start → Database core: initializes · App startup configures persistence.
- App start → Sync manager: enables · Startup wires offline synchronization support.
- API routes → Auth deps: protects · Protected endpoints depend on auth helpers.
- Domain services → Config: reads · Business logic uses runtime configuration.
- Domain services → License: checks · Services consult license policy where needed.
- API routes → Messages: messages · API responses use localized backend messages.
- Auth deps → Security utils: uses · Auth depends on shared security helpers.
- Sync manager → Data models: tracks · Sync state is stored alongside domain models.
- Flutter app → State providers: bootstraps · App startup registers shared UI state.
- Flutter app → API client: connects · The client is wired to the API boundary.
- Flutter app → Screens: navigates · Main app drives screen routing and layout.
- Screens → Widgets: composes · Screens are built from reusable widgets.
- State providers → API client: invokes · State actions call the HTTP services.
- Screens → State providers: consumes · UI reads auth, cart, theme, language, and license state.
- Flutter app → Localizations: localizes · App uses generated translation resources.
- API client → API routes: requests · Client features map to backend feature routes.
- Web build → Deployed web: packaged as · Compiled web app is reused in the deployment bundle.
- Vercel API → App start: wraps · Serverless entrypoint exposes the backend application.
- Deployed web → Flutter app: serves · Static bundle serves the Flutter web client.
