# bhoomika7860/suvidha architecture

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

- Interactive diagram: https://gitdiagram.com/bhoomika7860/suvidha
- Repository: https://github.com/bhoomika7860/suvidha

## Overview

#### Purpose and Entry Points
PharmaCore360 is a role-based pharmacy/store operations system: daily sales reporting, purchasing, deliveries, expenses, receivables (“udhaar”), staff tasks, multi-store management, analytics, exports, and audit history. The React SPA starts at `frontend/src/main.jsx`, composes application state in `frontend/src/App.jsx`, and maps protected role-specific views through `frontend/src/routes/AppRoutes.jsx`. The FastAPI backend is bootstrapped by `backend/app/main.py`.

#### Frontend Application Shell and Access Control
Authentication state is centralized in `frontend/src/contexts/AuthContext.jsx` and consumed through `frontend/src/hooks/useAuth.js`. Route access is gated by `frontend/src/routes/ProtectedRoute.jsx` and `frontend/src/components/auth/ProtectedRoute.jsx`; layout differs for manager, owner, and staff roles via `frontend/src/components/layout/ManagerLayout.jsx`, `frontend/src/components/layout/OwnerLayout.jsx`, and `frontend/src/components/layout/StaffLayout.jsx`. API communication is centralized in `frontend/src/api/api.js`, with domain-specific service adapters under `frontend/src/services/`.

#### Backend API, Authentication, and Authorization
FastAPI routes expose the domain API from `backend/app/routes/`, with login/auth endpoints in `backend/app/routes/auth.py`. Token creation/validation and password/security mechanics are separated into `backend/app/core/token.py` and `backend/app/core/security.py`. Endpoint-level identity and role enforcement flow through `backend/app/dependencies/auth.py` and `backend/app/dependencies/roles.py`, forming the primary trust boundary between browser clients and business data.

#### Persistence and Domain Model
Database setup is owned by `backend/app/database.py`; persistent entities are organized as ORM models in `backend/app/models/`, with request/response contracts in parallel under `backend/app/schemas/`. The core operational aggregate is daily reporting (`backend/app/models/daily_report.py`), connected to sales/payment capture, purchases, expenses, deliveries, and udhaar. Related accounting/operations records include `backend/app/models/payment_machine_entry.py`, `backend/app/models/purchase.py`, and `backend/app/models/expense.py`.

#### Daily Reporting and Financial Operations Flow
Manager/staff workflows assemble a daily report through `frontend/src/pages/manager/DailyReport.jsx` and modular entry sections such as `frontend/src/components/dailyReport/SalesSection.jsx`, `frontend/src/components/dailyReport/PurchaseSection.jsx`, and `frontend/src/components/dailyReport/ExpenseSection.jsx`. These invoke corresponding backend resources, principally `backend/app/routes/daily_reports.py`, `backend/app/routes/purchase.py`, and `backend/app/routes/expenses.py`. Owners consume completed/history detail through `frontend/src/pages/owner/DailyReports.jsx` and `frontend/src/pages/owner/ReportDetails.jsx`.

#### Operational Workflows
Deliveries are recorded and assigned through `backend/app/routes/deliveries.py` and `backend/app/routes/delivery_assignments.py`, surfaced in `frontend/src/pages/delivery/Delivery.jsx`. Purchasing includes both received purchases and purchase orders, backed by `backend/app/routes/purchase.py` and `backend/app/routes/purchase_orders.py`. Staff coordination is modeled through `backend/app/models/task.py` and exposed through `backend/app/routes/tasks.py`, with role-specific pages including `frontend/src/pages/staff/StaffTasks.jsx`.

#### Oversight, Reporting, and Integrations
Analytics, export, and audit functions provide owner/manager oversight through `backend/app/routes/analytics.py`, `backend/app/routes/export.py`, and `backend/app/routes/audit_logs.py`; export generation is isolated in `backend/app/services/export_service.py`. Bill and delivery evidence cross the API/file boundary via upload directories `backend/app/uploads/bills` and `backend/app/uploads/delivery_bills`. The frontend includes Firebase setup and a messaging service worker at `frontend/src/firebase.js` and `frontend/public/firebase-messaging-sw.js`, indicating Firebase-based notifications. Deployment-facing artifacts include `frontend/vercel.json`; backend runtime dependencies are declared in `backend/requirements.txt`.

Main entry points: [`frontend/src/routes/ProtectedRoute.jsx`](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/routes/ProtectedRoute.jsx) (Protected access), [`frontend/src/api/api.js`](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/api/api.js) (API client), [`backend/app/dependencies/auth.py`](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/dependencies/auth.py) (Identity & role enforcement), [`frontend/src/App.jsx`](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/App.jsx) (App state shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_entry["SPA entry<br/>React bootstrap<br/>[main.jsx]"]
  node_app_shell["App state shell<br/>React app<br/>[App.jsx]"]
  node_auth_context["Auth state<br/>context + hook<br/>[AuthContext.jsx]"]
  node_routes["Role-specific routes<br/>router<br/>[AppRoutes.jsx]"]
  node_route_guard["Protected access<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_role_layouts["Role layouts<br/>UI layouts<br/>[ManagerLayout.jsx]"]
  node_daily_report_ui["Daily report entry<br/>manager workflow<br/>[DailyReport.jsx]"]
  node_oversight_ui["Owner report review<br/>owner workflow<br/>[DailyReports.jsx]"]
  node_delivery_ui["Delivery workspace<br/>operations workflow<br/>[Delivery.jsx]"]
  node_api_client{{"API client<br/>HTTP client<br/>[api.js]"}}
end

subgraph group_backend["FastAPI Backend"]
  node_api_app["FastAPI application<br/>API bootstrap<br/>[main.py]"]
  node_auth_api["Authentication API<br/>auth endpoints<br/>[auth.py]"]
  node_authz{{"Identity &amp; role enforcement<br/>dependencies<br/>[auth.py]"}}
  node_token_security["Token &amp; password security<br/>security core<br/>[token.py]"]
  node_operations_api["Operational APIs<br/>domain routes<br/>[daily_reports.py]"]
  node_oversight_api["Analytics, export &amp; audit<br/>oversight routes<br/>[analytics.py]"]
  node_export_service["Export generator<br/>backend service<br/>[export_service.py]"]
end

subgraph group_data["Data &amp; Integrations"]
  node_firebase{{"Firebase notifications<br/>messaging integration<br/>[firebase.js]"}}
  node_domain_models["Operational domain model<br/>ORM models<br/>[daily_report.py]"]
  node_database[("Database<br/>persistence<br/>[database.py]")]
  node_evidence_uploads["Bill evidence uploads<br/>file storage"]
end

node_spa_entry -->|"mounts"| node_app_shell
node_app_shell -->|"provides session state"| node_auth_context
node_app_shell -->|"renders"| node_routes
node_routes -->|"gates protected views"| node_route_guard
node_route_guard -->|"selects permitted shell"| node_role_layouts
node_route_guard -->|"allows manager/staff workflow"| node_daily_report_ui
node_route_guard -->|"allows owner review"| node_oversight_ui
node_route_guard -->|"allows delivery workflow"| node_delivery_ui
node_auth_context -->|"authenticates requests"| node_api_client
node_daily_report_ui -->|"submits financial entries"| node_api_client
node_oversight_ui -->|"reads reports and exports"| node_api_client
node_delivery_ui -->|"records deliveries"| node_api_client
node_api_client -->|"HTTPS API calls"| node_api_app
node_api_app -->|"serves login"| node_auth_api
node_api_app -->|"applies dependencies"| node_authz
node_auth_api -->|"issues and validates tokens"| node_token_security
node_authz -->|"verifies identity"| node_token_security
node_authz -->|"authorizes domain access"| node_operations_api
node_authz -->|"authorizes oversight access"| node_oversight_api
node_operations_api -->|"creates and updates records"| node_domain_models
node_oversight_api -->|"queries reporting history"| node_domain_models
node_domain_models -->|"persists"| node_database
node_operations_api -->|"stores bill evidence"| node_evidence_uploads
node_oversight_api -->|"generates exports"| node_export_service
node_firebase -.->|"notification-aware client session"| node_auth_context

click node_spa_entry "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/main.jsx"
click node_app_shell "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_routes "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/routes/AppRoutes.jsx"
click node_route_guard "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/routes/ProtectedRoute.jsx"
click node_role_layouts "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/components/layout/ManagerLayout.jsx"
click node_daily_report_ui "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/pages/manager/DailyReport.jsx"
click node_oversight_ui "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/pages/owner/DailyReports.jsx"
click node_delivery_ui "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/pages/delivery/Delivery.jsx"
click node_api_client "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/api/api.js"
click node_firebase "https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/firebase.js"
click node_api_app "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/routes/auth.py"
click node_authz "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/dependencies/auth.py"
click node_token_security "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/core/token.py"
click node_operations_api "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/routes/daily_reports.py"
click node_oversight_api "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/routes/analytics.py"
click node_export_service "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/services/export_service.py"
click node_domain_models "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/models/daily_report.py"
click node_database "https://github.com/bhoomika7860/suvidha/blob/main/backend/app/database.py"
click node_evidence_uploads "https://github.com/bhoomika7860/suvidha/tree/main/backend/app/uploads/bills"

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_spa_entry,node_app_shell,node_auth_context,node_routes,node_route_guard,node_role_layouts,node_daily_report_ui,node_oversight_ui,node_delivery_ui,node_api_client toneBlue
class node_api_app,node_auth_api,node_authz,node_token_security,node_operations_api,node_oversight_api,node_export_service toneAmber
class node_firebase,node_domain_models,node_database,node_evidence_uploads toneMint
```

## Components

### React SPA

- [SPA entry](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/main.jsx): React bootstrap · `frontend/src/main.jsx`
- [App state shell](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/App.jsx): React app · `frontend/src/App.jsx`
- [Auth state](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/contexts/AuthContext.jsx): context + hook · `frontend/src/contexts/AuthContext.jsx`
- [Role-specific routes](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/routes/AppRoutes.jsx): router · `frontend/src/routes/AppRoutes.jsx`
- [Protected access](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/routes/ProtectedRoute.jsx): route guard · Enforces authenticated role access before views load. · `frontend/src/routes/ProtectedRoute.jsx`
- [Role layouts](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/components/layout/ManagerLayout.jsx): UI layouts · Manager, owner, and staff shells. · `frontend/src/components/layout/ManagerLayout.jsx`
- [Daily report entry](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/pages/manager/DailyReport.jsx): manager workflow · Sales, purchase, and expense sections assemble daily reports. · `frontend/src/pages/manager/DailyReport.jsx`
- [Owner report review](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/pages/owner/DailyReports.jsx): owner workflow · Completed reports and details. · `frontend/src/pages/owner/DailyReports.jsx`
- [Delivery workspace](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/pages/delivery/Delivery.jsx): operations workflow · `frontend/src/pages/delivery/Delivery.jsx`
- [API client](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/api/api.js): HTTP client · Central browser-to-backend communication. · `frontend/src/api/api.js`

### FastAPI Backend

- [FastAPI application](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/main.py): API bootstrap · `backend/app/main.py`
- [Authentication API](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/routes/auth.py): auth endpoints · `backend/app/routes/auth.py`
- [Identity & role enforcement](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/dependencies/auth.py): dependencies · Primary browser-to-business-data trust boundary. · `backend/app/dependencies/auth.py`
- [Token & password security](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/core/token.py): security core · `backend/app/core/token.py`
- [Operational APIs](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/routes/daily_reports.py): domain routes · Daily reports, purchases, expenses, deliveries, assignments, and tasks. · `backend/app/routes/daily_reports.py`
- [Analytics, export & audit](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/routes/analytics.py): oversight routes · `backend/app/routes/analytics.py`
- [Export generator](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/services/export_service.py): backend service · `backend/app/services/export_service.py`

### Data & Integrations

- [Firebase notifications](https://github.com/bhoomika7860/suvidha/blob/main/frontend/src/firebase.js): messaging integration · `frontend/src/firebase.js`
- [Operational domain model](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/models/daily_report.py): ORM models · Daily reports link sales, payments, purchases, expenses, deliveries, udhaar, and tasks. · `backend/app/models/daily_report.py`
- [Database](https://github.com/bhoomika7860/suvidha/blob/main/backend/app/database.py): persistence · `backend/app/database.py`
- [Bill evidence uploads](https://github.com/bhoomika7860/suvidha/tree/main/backend/app/uploads/bills): file storage · Uploaded bill and delivery evidence. · `backend/app/uploads/bills`

## Connections

- SPA entry → App state shell: mounts
- App state shell → Auth state: provides session state
- App state shell → Role-specific routes: renders
- Role-specific routes → Protected access: gates protected views
- Protected access → Role layouts: selects permitted shell
- Protected access → Daily report entry: allows manager/staff workflow
- Protected access → Owner report review: allows owner review
- Protected access → Delivery workspace: allows delivery workflow
- Auth state → API client: authenticates requests
- Daily report entry → API client: submits financial entries
- Owner report review → API client: reads reports and exports
- Delivery workspace → API client: records deliveries
- API client → FastAPI application: HTTPS API calls
- FastAPI application → Authentication API: serves login
- FastAPI application → Identity & role enforcement: applies dependencies
- Authentication API → Token & password security: issues and validates tokens
- Identity & role enforcement → Token & password security: verifies identity
- Identity & role enforcement → Operational APIs: authorizes domain access
- Identity & role enforcement → Analytics, export & audit: authorizes oversight access
- Operational APIs → Operational domain model: creates and updates records
- Analytics, export & audit → Operational domain model: queries reporting history
- Operational domain model → Database: persists
- Operational APIs → Bill evidence uploads: stores bill evidence
- Analytics, export & audit → Export generator: generates exports
- Firebase notifications → Auth state: notification-aware client session