# thunyaponle/agnos architecture

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

- Interactive diagram: https://gitdiagram.com/thunyaponle/agnos
- Repository: https://github.com/thunyaponle/agnos

## Overview

#### Purpose and Runtime
This repository contains `Agnos/hospital-middleware`, a Go HTTP middleware/API service for hospital staff and patient operations. The documented addition is `POST /api/patient/create`, which persists a new patient record. It runs as a containerized service, with PostgreSQL and Nginx deployment/proxy artifacts in `Agnos/hospital-middleware/docker-compose.yml`, `Agnos/hospital-middleware/Dockerfile`, and `Agnos/hospital-middleware/nginx.conf`.

#### Application Entry and Composition
`Agnos/hospital-middleware/cmd/server/main.go` is the executable entry point. It is responsible for assembling configuration, database access, repositories, services, controllers, and HTTP routes. Configuration is centralized in `Agnos/hospital-middleware/config/config.go`; PostgreSQL connection setup is in `Agnos/hospital-middleware/database/postgres.go`.

#### HTTP Routing and Access Boundary
`Agnos/hospital-middleware/routes/routes.go` defines the public API surface and connects endpoints to controllers. `Agnos/hospital-middleware/middleware/auth.go` is the authentication boundary for protected requests, while `Agnos/hospital-middleware/service/jwt.go` provides JWT-related behavior. Requests should pass routing/authentication before reaching domain handlers.

#### Controller Layer
HTTP request parsing, response construction, and delegation are separated into patient and staff controllers:
- `Agnos/hospital-middleware/controller/patient_controller.go`
- `Agnos/hospital-middleware/controller/staff_controller.go`

The patient controller owns the create-patient endpoint path’s transport concerns; it delegates business work rather than directly owning SQL access.

#### Domain Services
Service classes contain the application-level patient and staff workflows:
- `Agnos/hospital-middleware/service/patient_service.go`
- `Agnos/hospital-middleware/service/staff_service.go`

They operate on domain models in `Agnos/hospital-middleware/model/patient.go`, `Agnos/hospital-middleware/model/staff.go`, and `Agnos/hospital-middleware/model/hospital.go`. JWT support is a cross-cutting service dependency rather than a persistence concern.

#### Persistence Boundary
Repository interfaces separate services from concrete storage:
- `Agnos/hospital-middleware/repository/patient_repository.go`
- `Agnos/hospital-middleware/repository/staff_repository.go`
- `Agnos/hospital-middleware/repository/hospital_repository.go`

PostgreSQL implementations live in `Agnos/hospital-middleware/repository/patient_postgres.go`, `Agnos/hospital-middleware/repository/staff_postgres.go`, and `Agnos/hospital-middleware/repository/hospital_postgres.go`. Schema initialization is represented by `Agnos/hospital-middleware/migrations/001_init.sql`. Mock repositories allow service logic to be substituted away from PostgreSQL.

#### Primary Flows
For patient creation, control flows: route → auth middleware when applicable → patient controller → patient service → patient repository interface → PostgreSQL repository → database. The response returns through the controller. Staff flows follow the equivalent controller/service/repository chain. A distinct outbound integration client, `Agnos/hospital-middleware/client/hospital_a_client.go`, forms a boundary to an external Hospital A service; its calls should remain isolated from HTTP handlers and database repositories.

Main entry points: [`Agnos/hospital-middleware/cmd/server/main.go`](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/cmd/server/main.go) (Server composition), [`Agnos/hospital-middleware/service/patient_service.go`](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/patient_service.go) (Patient service), [`Agnos/hospital-middleware/routes/routes.go`](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/routes/routes.go) (API routes), [`Agnos/hospital-middleware/service/staff_service.go`](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/staff_service.go) (Staff service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Deployment"]
  node_compose{{"Container deployment<br/>Docker Compose<br/>[docker-compose.yml]"}}
  node_nginx["Nginx proxy<br/>reverse proxy<br/>[nginx.conf]"]
  node_main{{"Server composition<br/>Go entry point<br/>[main.go]"}}
  node_config["Configuration<br/>app config<br/>[config.go]"]
end

subgraph group_http["HTTP API"]
  node_routes["API routes<br/>HTTP routing<br/>[routes.go]"]
  node_auth["Auth middleware<br/>request middleware<br/>[auth.go]"]
  node_patient_controller["Patient controller<br/>HTTP controller"]
  node_staff_controller["Staff controller<br/>HTTP controller"]
end

subgraph group_domain["Application Layers"]
  node_jwt["JWT service<br/>token service<br/>[jwt.go]"]
  node_patient_service["Patient service<br/>domain service<br/>[patient_service.go]"]
  node_staff_service["Staff service<br/>domain service<br/>[staff_service.go]"]
  node_models["Hospital domain models<br/>[patient.go]"]
  node_hospital_a{{"Hospital A client<br/>external integration client"}}
end

subgraph group_persistence["Persistence"]
  node_patient_repo["Patient repository<br/>repository interface"]
  node_staff_repo["Staff repository<br/>repository interface"]
  node_hospital_repo["Hospital repository<br/>repository interface"]
  node_postgres_repos["PostgreSQL repositories<br/>repository implementations"]
  node_postgres_setup["PostgreSQL connection<br/>database setup<br/>[postgres.go]"]
  node_database[("PostgreSQL<br/>relational database")]
  node_migration["Initial schema<br/>SQL migration<br/>[001_init.sql]"]
end

node_compose -->|"runs"| node_nginx
node_compose -->|"runs"| node_main
node_compose -->|"runs"| node_database
node_nginx -->|"proxies requests"| node_routes
node_main -->|"loads"| node_config
node_main -->|"initializes"| node_postgres_setup
node_main -->|"registers"| node_routes
node_main -.->|"wires"| node_patient_service
node_main -.->|"wires"| node_staff_service
node_routes -->|"protects requests"| node_auth
node_auth -->|"validates tokens"| node_jwt
node_auth -->|"authorizes"| node_patient_controller
node_routes -->|"dispatches"| node_staff_controller
node_patient_controller -->|"delegates create patient"| node_patient_service
node_staff_controller -->|"delegates"| node_staff_service
node_patient_service -->|"uses"| node_patient_repo
node_staff_service -->|"uses"| node_staff_repo
node_patient_service -->|"operates on"| node_models
node_staff_service -->|"operates on"| node_models
node_patient_service -->|"calls when needed"| node_hospital_a
node_patient_repo -.->|"implemented by"| node_postgres_repos
node_staff_repo -.->|"implemented by"| node_postgres_repos
node_hospital_repo -.->|"implemented by"| node_postgres_repos
node_postgres_repos -->|"uses connection"| node_postgres_setup
node_postgres_setup -->|"connects"| node_database
node_migration -->|"initializes schema"| node_database

click node_compose "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/docker-compose.yml"
click node_nginx "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/nginx.conf"
click node_main "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/cmd/server/main.go"
click node_config "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/config/config.go"
click node_routes "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/routes/routes.go"
click node_auth "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/middleware/auth.go"
click node_patient_controller "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/controller/patient_controller.go"
click node_staff_controller "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/controller/staff_controller.go"
click node_jwt "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/jwt.go"
click node_patient_service "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/patient_service.go"
click node_staff_service "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/staff_service.go"
click node_models "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/model/patient.go"
click node_hospital_a "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/client/hospital_a_client.go"
click node_patient_repo "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/patient_repository.go"
click node_staff_repo "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/staff_repository.go"
click node_hospital_repo "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/hospital_repository.go"
click node_postgres_repos "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/patient_postgres.go"
click node_postgres_setup "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/database/postgres.go"
click node_migration "https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/migrations/001_init.sql"

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_compose,node_nginx,node_main,node_config toneBlue
class node_routes,node_auth,node_patient_controller,node_staff_controller toneAmber
class node_jwt,node_patient_service,node_staff_service,node_models,node_hospital_a toneMint
class node_patient_repo,node_staff_repo,node_hospital_repo,node_postgres_repos,node_postgres_setup,node_database,node_migration toneRose
```

## Components

### Runtime & Deployment

- [Container deployment](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/docker-compose.yml): Docker Compose · Runs the service with PostgreSQL and Nginx. · `Agnos/hospital-middleware/docker-compose.yml`
- [Nginx proxy](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/nginx.conf): reverse proxy · `Agnos/hospital-middleware/nginx.conf`
- [Server composition](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/cmd/server/main.go): Go entry point · Wires configuration, database, repositories, services, controllers, and routes. · `Agnos/hospital-middleware/cmd/server/main.go`
- [Configuration](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/config/config.go): app config · `Agnos/hospital-middleware/config/config.go`

### HTTP API

- [API routes](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/routes/routes.go): HTTP routing · Defines public endpoints including POST /api/patient/create. · `Agnos/hospital-middleware/routes/routes.go`
- [Auth middleware](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/middleware/auth.go): request middleware · Protects applicable requests before handlers. · `Agnos/hospital-middleware/middleware/auth.go`
- [Patient controller](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/controller/patient_controller.go): HTTP controller · Handles patient request parsing and responses. · `Agnos/hospital-middleware/controller/patient_controller.go`
- [Staff controller](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/controller/staff_controller.go): HTTP controller · `Agnos/hospital-middleware/controller/staff_controller.go`

### Application Layers

- [JWT service](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/jwt.go): token service · `Agnos/hospital-middleware/service/jwt.go`
- [Patient service](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/patient_service.go): domain service · Owns patient workflows including creation. · `Agnos/hospital-middleware/service/patient_service.go`
- [Staff service](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/service/staff_service.go): domain service · `Agnos/hospital-middleware/service/staff_service.go`
- [Hospital domain models](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/model/patient.go): domain models · Patient, staff, and hospital entities. · `Agnos/hospital-middleware/model/patient.go`
- [Hospital A client](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/client/hospital_a_client.go): external integration client · Isolates outbound Hospital A calls. · `Agnos/hospital-middleware/client/hospital_a_client.go`

### Persistence

- [Patient repository](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/patient_repository.go): repository interface · `Agnos/hospital-middleware/repository/patient_repository.go`
- [Staff repository](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/staff_repository.go): repository interface · `Agnos/hospital-middleware/repository/staff_repository.go`
- [Hospital repository](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/hospital_repository.go): repository interface · `Agnos/hospital-middleware/repository/hospital_repository.go`
- [PostgreSQL repositories](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/repository/patient_postgres.go): repository implementations · Concrete patient, staff, and hospital persistence. · `Agnos/hospital-middleware/repository/patient_postgres.go`
- [PostgreSQL connection](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/database/postgres.go): database setup · `Agnos/hospital-middleware/database/postgres.go`
- **PostgreSQL**: relational database
- [Initial schema](https://github.com/thunyaponle/agnos/blob/main/Agnos/hospital-middleware/migrations/001_init.sql): SQL migration · `Agnos/hospital-middleware/migrations/001_init.sql`

## Connections

- Container deployment → Nginx proxy: runs
- Container deployment → Server composition: runs
- Container deployment → PostgreSQL: runs
- Nginx proxy → API routes: proxies requests
- Server composition → Configuration: loads
- Server composition → PostgreSQL connection: initializes
- Server composition → API routes: registers
- Server composition → Patient service: wires
- Server composition → Staff service: wires
- API routes → Auth middleware: protects requests
- Auth middleware → JWT service: validates tokens
- Auth middleware → Patient controller: authorizes
- API routes → Staff controller: dispatches
- Patient controller → Patient service: delegates create patient
- Staff controller → Staff service: delegates
- Patient service → Patient repository: uses
- Staff service → Staff repository: uses
- Patient service → Hospital domain models: operates on
- Staff service → Hospital domain models: operates on
- Patient service → Hospital A client: calls when needed
- Patient repository → PostgreSQL repositories: implemented by
- Staff repository → PostgreSQL repositories: implemented by
- Hospital repository → PostgreSQL repositories: implemented by
- PostgreSQL repositories → PostgreSQL connection: uses connection
- PostgreSQL connection → PostgreSQL: connects
- Initial schema → PostgreSQL: initializes schema