# bigpumpum001/pharventory architecture

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

- Interactive diagram: https://gitdiagram.com/bigpumpum001/pharventory
- Repository: https://github.com/bigpumpum001/pharventory

## Overview

Pharventory is a pharmacy inventory system whose main workflow is staff authentication, inventory and batch management, dispensing, then receipt and stock-movement review. The Next.js interface presents these workflows; the NestJS API implements authentication and domain operations, with PostgreSQL as the documented primary store. Dashboard analytics, Excel import, image uploads, and user/role administration are additional capabilities. Edges are limited to relationships shown in excerpts, the source index, or README; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`frontend/app/inventory/page.tsx`](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/inventory/page.tsx) (Inventory workspace), [`backend/src/modules/dispense/dispense.service.ts`](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/dispense/dispense.service.ts) (FEFO and transaction logic), [`frontend/app/dispense/page.tsx`](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/dispense/page.tsx) (Dispensing workspace), [`frontend/app/dashboard/page.tsx`](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/dashboard/page.tsx) (Dashboard analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Staff interface"]
  node_login["Sign in<br/>[page.tsx]"]
  node_dashboard["Dashboard analytics<br/>[page.tsx]"]
  node_inventory_ui["Inventory workspace<br/>[page.tsx]"]
  node_dispense_ui["Dispensing workspace<br/>[page.tsx]"]
  node_receipt_ui["Receipt history<br/>[page.tsx]"]
  node_stocklog_ui["Stock movement view<br/>[page.tsx]"]
end

subgraph group_security["Identity and access"]
  node_auth_api["Authentication API<br/>[auth.service.ts]"]
  node_user_admin["User and role administration<br/>[users.service.ts]"]
end

subgraph group_inventory["Inventory operations"]
  node_medicine_api["Medicine management"]
  node_batch_api["Batch management"]
  node_catalog["Categories and units"]
  node_excel_import["Spreadsheet import"]
  node_image_upload["Medicine image upload"]
end

subgraph group_transactions["Dispensing and records"]
  node_dispense_api["Dispense processing"]
  node_dispense_service["FEFO and transaction logic"]
  node_receipts["Receipt records"]
  node_stock_logs["Stock movement records"]
end

subgraph group_platform["API and persistence"]
  node_api["NestJS application<br/>[main.ts]"]
  node_postgres[("PostgreSQL store")]
  node_cloud_storage[("Google Cloud Storage")]
end

node_staff(("Pharmacy staff"))

node_staff -->|"signs in"| node_login
node_staff -->|"manages stock"| node_inventory_ui
node_staff -->|"dispenses medicines"| node_dispense_ui
node_staff -->|"reviews receipts"| node_receipt_ui
node_staff -->|"reviews movements"| node_stocklog_ui
node_dashboard -->|"summarizes stock"| node_inventory_ui
node_dashboard -->|"summarizes sales"| node_dispense_ui
node_login -.->|"requests authentication"| node_auth_api
node_inventory_ui -.->|"manages medicines"| node_medicine_api
node_inventory_ui -.->|"manages batches"| node_batch_api
node_inventory_ui -.->|"maintains catalog"| node_catalog
node_inventory_ui -.->|"imports spreadsheet"| node_excel_import
node_inventory_ui -.->|"uploads images"| node_image_upload
node_dispense_ui -.->|"submits dispense"| node_dispense_api
node_receipt_ui -.->|"retrieves history"| node_receipts
node_stocklog_ui -.->|"retrieves movements"| node_stock_logs
node_auth_api -->|"looks up user"| node_user_admin
node_api -->|"persists domain data"| node_postgres
node_dispense_api -->|"dispatches dispense"| node_dispense_service
node_dispense_service -->|"uses batch records"| node_batch_api
node_dispense_service -->|"uses receipt records"| node_receipts
node_dispense_service -->|"uses movement records"| node_stock_logs
node_image_upload -->|"uploads image"| node_cloud_storage

click node_login "https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/login/page.tsx"
click node_dashboard "https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/dashboard/page.tsx"
click node_inventory_ui "https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/inventory/page.tsx"
click node_dispense_ui "https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/dispense/page.tsx"
click node_receipt_ui "https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/receipt/page.tsx"
click node_stocklog_ui "https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/stocklogs/page.tsx"
click node_auth_api "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/auth/auth.service.ts"
click node_user_admin "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/users/users.service.ts"
click node_medicine_api "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/medicines/medicines.controller.ts"
click node_batch_api "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/medicine-batches/medicine-batches.controller.ts"
click node_catalog "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/category/category.service.ts"
click node_excel_import "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/import-excel/import-excel.service.ts"
click node_image_upload "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/upload/upload.controller.ts"
click node_dispense_api "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/dispense/dispense.controller.ts"
click node_dispense_service "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/dispense/dispense.service.ts"
click node_receipts "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/receipts/receipts.controller.ts"
click node_stock_logs "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/stock-logs/stock-logs.controller.ts"
click node_api "https://github.com/bigpumpum001/pharventory/blob/main/backend/src/main.ts"

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_login,node_dashboard,node_inventory_ui,node_dispense_ui,node_receipt_ui,node_stocklog_ui toneBlue
class node_auth_api,node_user_admin toneAmber
class node_medicine_api,node_batch_api,node_catalog,node_excel_import,node_image_upload toneMint
class node_dispense_api,node_dispense_service,node_receipts,node_stock_logs toneRose
class node_api,node_postgres,node_cloud_storage,node_staff toneIndigo
```

## Components

### Staff interface

- [Sign in](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [Dashboard analytics](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Inventory workspace](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/inventory/page.tsx): `frontend/app/inventory/page.tsx`
- [Dispensing workspace](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/dispense/page.tsx): `frontend/app/dispense/page.tsx`
- [Receipt history](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/receipt/page.tsx): `frontend/app/receipt/page.tsx`
- [Stock movement view](https://github.com/bigpumpum001/pharventory/blob/main/frontend/app/stocklogs/page.tsx): `frontend/app/stocklogs/page.tsx`

### Identity and access

- [Authentication API](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/auth/auth.service.ts): `backend/src/modules/auth/auth.service.ts`
- [User and role administration](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/users/users.service.ts): `backend/src/modules/users/users.service.ts`

### Inventory operations

- [Medicine management](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/medicines/medicines.controller.ts): `backend/src/modules/medicines/medicines.controller.ts`
- [Batch management](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/medicine-batches/medicine-batches.controller.ts): `backend/src/modules/medicine-batches/medicine-batches.controller.ts`
- [Categories and units](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/category/category.service.ts): `backend/src/modules/category/category.service.ts`
- [Spreadsheet import](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/import-excel/import-excel.service.ts): `backend/src/modules/import-excel/import-excel.service.ts`
- [Medicine image upload](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/upload/upload.controller.ts): `backend/src/modules/upload/upload.controller.ts`

### Dispensing and records

- [Dispense processing](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/dispense/dispense.controller.ts): `backend/src/modules/dispense/dispense.controller.ts`
- [FEFO and transaction logic](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/dispense/dispense.service.ts): `backend/src/modules/dispense/dispense.service.ts`
- [Receipt records](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/receipts/receipts.controller.ts): `backend/src/modules/receipts/receipts.controller.ts`
- [Stock movement records](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/modules/stock-logs/stock-logs.controller.ts): `backend/src/modules/stock-logs/stock-logs.controller.ts`

### API and persistence

- [NestJS application](https://github.com/bigpumpum001/pharventory/blob/main/backend/src/main.ts): `backend/src/main.ts`
- **PostgreSQL store**
- **Google Cloud Storage**

### Other components

- **Pharmacy staff**

## Connections

- Pharmacy staff → Sign in: signs in
- Pharmacy staff → Inventory workspace: manages stock
- Pharmacy staff → Dispensing workspace: dispenses medicines
- Pharmacy staff → Receipt history: reviews receipts
- Pharmacy staff → Stock movement view: reviews movements
- Dashboard analytics → Inventory workspace: summarizes stock (evidence: `frontend/app/dashboard/page.tsx`)
- Dashboard analytics → Dispensing workspace: summarizes sales
- Sign in → Authentication API: requests authentication
- Inventory workspace → Medicine management: manages medicines
- Inventory workspace → Batch management: manages batches
- Inventory workspace → Categories and units: maintains catalog
- Inventory workspace → Spreadsheet import: imports spreadsheet
- Inventory workspace → Medicine image upload: uploads images
- Dispensing workspace → Dispense processing: submits dispense
- Receipt history → Receipt records: retrieves history
- Stock movement view → Stock movement records: retrieves movements
- Authentication API → User and role administration: looks up user (evidence: `backend/src/modules/auth/auth.service.ts`)
- NestJS application → PostgreSQL store: persists domain data
- Dispense processing → FEFO and transaction logic: dispatches dispense (evidence: `backend/src/modules/dispense/dispense.controller.ts`)
- FEFO and transaction logic → Batch management: uses batch records (evidence: `backend/src/modules/dispense/dispense.service.ts`)
- FEFO and transaction logic → Receipt records: uses receipt records (evidence: `backend/src/modules/dispense/dispense.service.ts`)
- FEFO and transaction logic → Stock movement records: uses movement records (evidence: `backend/src/modules/dispense/dispense.service.ts`)
- Medicine image upload → Google Cloud Storage: uploads image (evidence: `backend/src/modules/upload/upload.controller.ts`)
