# institutofloravida/pharma-api architecture

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

- Interactive diagram: https://gitdiagram.com/institutofloravida/pharma-api
- Repository: https://github.com/institutofloravida/pharma-api

## Overview

Pharma API is a NestJS service for institutional medicine inventory and dispensing. The principal visible workflow is an authenticated HTTP request to preview dispensing, which invokes application logic that checks medicine stock and selects eligible batches. Other substantial domain branches cover stock movements, inventory and reports, and management of operators and reference records. The excerpts establish the preview and report-controller links; other capabilities are represented from the source tree, but their runtime wiring was not sampled.

Main entry points: [`src/domain/pharma/application/repositories`](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/repositories) (Repository Contracts), [`src/infra/http/controllers`](https://github.com/institutofloravida/pharma-api/tree/master/src/infra/http/controllers) (HTTP Controllers), [`src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts`](https://github.com/institutofloravida/pharma-api/blob/master/src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts) (Dispense Preview), [`src/domain/pharma/application/use-cases/operator`](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/operator) (Operator Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_controllers["HTTP Controllers"]
  node_auth["JWT and Roles"]
end

subgraph group_inventory["Inventory Operations"]
  node_med_stock["Medicine Stock"]
  node_batch_stock["Batch Stock"]
  node_movements["Stock Movements"]
  node_inventory_queries["Inventory Queries"]
  node_reports["Reports"]
  node_metrics["Metrics and Alerts"]
  node_use_medicine["Medicine Utilization"]
end

subgraph group_dispensing["Dispensing"]
  node_dispense_preview["Dispense Preview"]
  node_dispense_lifecycle["Dispensation Records"]
end

subgraph group_admin["Administration"]
  node_operators["Operator Management"]
  node_institutions["Institution Records"]
  node_reference_data["Medicine Reference Data"]
  node_patients["Patient Records"]
end

subgraph group_platform["Domain and Persistence"]
  node_repository_contracts["Repository Contracts"]
  node_entities["Pharma Entities"]
  node_core["Core Primitives"]
  node_prisma[("Prisma Database")]
  node_crypto["Cryptography Adapters"]
end

node_client(("API Client"))

node_client -.->|"sends requests"| node_controllers
node_controllers -->|"invokes preview"| node_dispense_preview
node_dispense_preview -->|"reads stock"| node_med_stock
node_dispense_preview -->|"lists batches"| node_batch_stock
node_controllers -->|"dispatches reports"| node_reports
node_controllers -.->|"guards requests"| node_auth
node_movements -.->|"uses contracts"| node_repository_contracts
node_inventory_queries -.->|"uses contracts"| node_repository_contracts
node_reports -.->|"uses contracts"| node_repository_contracts
node_metrics -.->|"uses contracts"| node_repository_contracts
node_dispense_lifecycle -.->|"uses contracts"| node_repository_contracts
node_operators -.->|"uses contracts"| node_repository_contracts
node_institutions -.->|"uses contracts"| node_repository_contracts
node_reference_data -.->|"uses contracts"| node_repository_contracts
node_patients -.->|"uses contracts"| node_repository_contracts
node_use_medicine -.->|"uses contracts"| node_repository_contracts
node_repository_contracts -.->|"implemented by"| node_prisma
node_repository_contracts -.->|"models data"| node_entities
node_dispense_preview -->|"returns Either"| node_core
node_operators -.->|"uses cryptography"| node_crypto

click node_controllers "https://github.com/institutofloravida/pharma-api/tree/master/src/infra/http/controllers"
click node_auth "https://github.com/institutofloravida/pharma-api/tree/master/src/infra/auth"
click node_dispense_preview "https://github.com/institutofloravida/pharma-api/blob/master/src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts"
click node_dispense_lifecycle "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/dispensation"
click node_med_stock "https://github.com/institutofloravida/pharma-api/blob/master/src/domain/pharma/application/repositories/medicines-stock-repository.ts"
click node_batch_stock "https://github.com/institutofloravida/pharma-api/blob/master/src/domain/pharma/application/repositories/batch-stocks-repository.ts"
click node_movements "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/movimentation"
click node_inventory_queries "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/inventory"
click node_reports "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/reports"
click node_metrics "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/metrics"
click node_operators "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/operator"
click node_institutions "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/institution"
click node_reference_data "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/auxiliary-records"
click node_patients "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/patient"
click node_use_medicine "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/use-medicine"
click node_repository_contracts "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/repositories"
click node_entities "https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/enterprise/entities"
click node_core "https://github.com/institutofloravida/pharma-api/tree/master/src/core"
click node_prisma "https://github.com/institutofloravida/pharma-api/tree/master/src/infra/database"
click node_crypto "https://github.com/institutofloravida/pharma-api/tree/master/src/infra/cryptography"

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_controllers,node_auth,node_client toneBlue
class node_med_stock,node_batch_stock,node_movements,node_inventory_queries,node_reports,node_metrics,node_use_medicine toneAmber
class node_dispense_preview,node_dispense_lifecycle toneMint
class node_operators,node_institutions,node_reference_data,node_patients toneRose
class node_repository_contracts,node_entities,node_core,node_prisma,node_crypto toneIndigo
```

## Components

### HTTP API

- [HTTP Controllers](https://github.com/institutofloravida/pharma-api/tree/master/src/infra/http/controllers): `src/infra/http/controllers`
- [JWT and Roles](https://github.com/institutofloravida/pharma-api/tree/master/src/infra/auth): `src/infra/auth`

### Inventory Operations

- [Medicine Stock](https://github.com/institutofloravida/pharma-api/blob/master/src/domain/pharma/application/repositories/medicines-stock-repository.ts): `src/domain/pharma/application/repositories/medicines-stock-repository.ts`
- [Batch Stock](https://github.com/institutofloravida/pharma-api/blob/master/src/domain/pharma/application/repositories/batch-stocks-repository.ts): `src/domain/pharma/application/repositories/batch-stocks-repository.ts`
- [Stock Movements](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/movimentation): `src/domain/pharma/application/use-cases/movimentation`
- [Inventory Queries](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/inventory): `src/domain/pharma/application/use-cases/inventory`
- [Reports](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/reports): `src/domain/pharma/application/use-cases/reports`
- [Metrics and Alerts](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/metrics): `src/domain/pharma/application/use-cases/metrics`
- [Medicine Utilization](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/use-medicine): `src/domain/pharma/application/use-cases/use-medicine`

### Dispensing

- [Dispense Preview](https://github.com/institutofloravida/pharma-api/blob/master/src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts): `src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts`
- [Dispensation Records](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/dispensation): `src/domain/pharma/application/use-cases/dispensation`

### Administration

- [Operator Management](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/operator): `src/domain/pharma/application/use-cases/operator`
- [Institution Records](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/institution): `src/domain/pharma/application/use-cases/institution`
- [Medicine Reference Data](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/auxiliary-records): `src/domain/pharma/application/use-cases/auxiliary-records`
- [Patient Records](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/use-cases/patient): `src/domain/pharma/application/use-cases/patient`

### Domain and Persistence

- [Repository Contracts](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/application/repositories): `src/domain/pharma/application/repositories`
- [Pharma Entities](https://github.com/institutofloravida/pharma-api/tree/master/src/domain/pharma/enterprise/entities): `src/domain/pharma/enterprise/entities`
- [Core Primitives](https://github.com/institutofloravida/pharma-api/tree/master/src/core): `src/core`
- [Prisma Database](https://github.com/institutofloravida/pharma-api/tree/master/src/infra/database): `src/infra/database`
- [Cryptography Adapters](https://github.com/institutofloravida/pharma-api/tree/master/src/infra/cryptography): `src/infra/cryptography`

### Other components

- **API Client**

## Connections

- API Client → HTTP Controllers: sends requests
- HTTP Controllers → Dispense Preview: invokes preview (evidence: `src/infra/http/controllers/dispensation/dispensation-preview.controller.ts`)
- Dispense Preview → Medicine Stock: reads stock (evidence: `src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts`)
- Dispense Preview → Batch Stock: lists batches (evidence: `src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts`)
- HTTP Controllers → Reports: dispatches reports (evidence: `src/infra/http/controllers/reports/get-inventory-report.controller.ts`)
- HTTP Controllers → JWT and Roles: guards requests (evidence: `src/infra/http/controllers/dispensation/dispensation-preview.controller.ts`)
- Stock Movements → Repository Contracts: uses contracts
- Inventory Queries → Repository Contracts: uses contracts
- Reports → Repository Contracts: uses contracts
- Metrics and Alerts → Repository Contracts: uses contracts
- Dispensation Records → Repository Contracts: uses contracts (evidence: `src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts`)
- Operator Management → Repository Contracts: uses contracts (evidence: `src/domain/pharma/application/use-cases/operator/authenticate-operator.ts`)
- Institution Records → Repository Contracts: uses contracts
- Medicine Reference Data → Repository Contracts: uses contracts
- Patient Records → Repository Contracts: uses contracts (evidence: `src/domain/pharma/application/use-cases/patient/update-patient.ts`)
- Medicine Utilization → Repository Contracts: uses contracts
- Repository Contracts → Prisma Database: implemented by
- Repository Contracts → Pharma Entities: models data (evidence: `src/domain/pharma/application/repositories/medicines-stock-repository.ts`)
- Dispense Preview → Core Primitives: returns Either (evidence: `src/domain/pharma/application/use-cases/dispensation/dispensation-preview.ts`)
- Operator Management → Cryptography Adapters: uses cryptography
