How arnaud-dev04/pharmagestion works
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: services Domain services · main.dart Flutter app · routes API routes · main.py App start
Components 21
Backend
FastAPI system of record with domain routes, services, models, sync, and persistence.
- App start · Bootstraps the backend application and wires the API surface.
backend/main.py - API routes · Feature-oriented endpoints for auth, stock, sales, POS, reports, sync, and admin.
backend/app/routes - Domain services · Coordinates pharmacy workflows before persistence.
backend/app/services - Data models · Core persistence model set for inventory, sales, people, pricing, and sync state.
backend/app/models - Schemas · Pydantic request/response contracts used by the API.
backend/app/schemas - Database core · Database wiring and engine/session configuration.
backend/app/database/core.py - Sync manager · Buffers and reconciles local operations for later synchronization.
backend/app/sync/sync_manager.py - Auth deps · JWT/auth dependencies shared by protected backend routes.
backend/app/auth/dependencies.py - Config · Environment-driven backend settings and mode selection.
backend/app/core/config.py - License · Backend license enforcement and entitlement logic.
backend/app/core/license.py - Messages · Backend French/English message catalogs and helpers.
backend/app/i18n/messages_en.json - Security utils · 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 · Main Flutter application entrypoint for desktop, web, and mobile.
frontend1/lib/main.dart - State providers · Provider-based state for auth, cart, theme, language, and license.
frontend1/lib/providers - API client · Network layer and feature services that call the backend API.
frontend1/lib/services/api_service.dart - Screens · Primary UI surfaces for login, dashboard, POS, stock, sales, restock, reports, settings, and users.
frontend1/lib/screens - Widgets · Reusable layout, dashboard, POS, stock, and form components.
frontend1/lib/widgets - Localizations · 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 · Compiled Flutter web output packaged for browser deployment.
frontend_build/index.html - Vercel API · Vercel entrypoint wrapping the backend for deployment.
deploy_vercel/api/index.py - Deployed web · Prebuilt web assets shipped with the Vercel deployment path.
deploy_vercel/frontend_build/index.html
Connections 23
- 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.