# zedzed34/agnos-backend architecture

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

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

## Overview

A Go/Gin hospital backend supports staff registration and login, then hospital-scoped patient search with a Hospital A external-lookup fallback and local caching. The README documents the layers and endpoints; sampled source confirms the authentication, search, routing, persistence, and fallback paths shown. Repository implementations for hospital and staff are represented by their tree paths, but their internals were not sampled.

Main entry points: [`cmd/api/main.go`](https://github.com/zedzed34/agnos-backend/blob/main/cmd/api/main.go) (API entrypoint), [`web/app.js`](https://github.com/zedzed34/agnos-backend/blob/main/web/app.js) (Web interface), [`internal/service/patient_service.go`](https://github.com/zedzed34/agnos-backend/blob/main/internal/service/patient_service.go) (Patient search), [`internal/handler/patient_handler.go`](https://github.com/zedzed34/agnos-backend/blob/main/internal/handler/patient_handler.go) (Patient handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Staff client"]
  node_staff(("Hospital staff"))
  node_web["Web interface<br/>[app.js]"]
end

subgraph group_api["HTTP API"]
  node_entry["API entrypoint<br/>[main.go]"]
  node_authhandler["Auth handlers<br/>[auth_handler.go]"]
  node_patienthandler["Patient handler<br/>[patient_handler.go]"]
  node_middleware["JWT middleware<br/>[auth_middleware.go]"]
  node_config["Runtime config<br/>[config.go]"]
end

subgraph group_logic["Domain services"]
  node_authservice["Authentication<br/>[auth_service.go]"]
  node_patientservice["Patient search<br/>[patient_service.go]"]
  node_domain["Domain models<br/>[patient.go]"]
end

subgraph group_data["Persistence and integrations"]
  node_hospitalrepo["Hospital repository<br/>[hospital_repo.go]"]
  node_staffrepo["Staff repository<br/>[staff_repo.go]"]
  node_patientrepo["Patient repository<br/>[patient_repo.go]"]
  node_hospitalclient["Hospital API client<br/>[hospital_client.go]"]
  node_postgres[("PostgreSQL")]
  node_hospitalapi["Hospital A API"]
end

node_staff -->|"uses"| node_web
node_web -->|"requests pages"| node_entry
node_web -->|"registers / logs in"| node_authhandler
node_web -->|"searches patients"| node_patienthandler
node_entry -->|"loads settings"| node_config
node_entry -->|"routes auth"| node_authhandler
node_entry -->|"protects search"| node_middleware
node_entry -->|"routes search"| node_patienthandler
node_authhandler -->|"calls"| node_authservice
node_authservice -->|"finds hospital"| node_hospitalrepo
node_authservice -->|"creates / finds staff"| node_staffrepo
node_patienthandler -->|"reads hospital claim"| node_middleware
node_patienthandler -->|"passes filters"| node_patientservice
node_patientservice -->|"searches locally"| node_patientrepo
node_patientservice -->|"fetches on fallback"| node_hospitalclient
node_patientservice -->|"caches result"| node_patientrepo
node_hospitalclient -.->|"requests patient"| node_hospitalapi
node_hospitalrepo -->|"reads hospitals"| node_postgres
node_staffrepo -->|"reads / writes staff"| node_postgres
node_patientrepo -->|"reads / upserts patients"| node_postgres
node_entry -->|"migrates / seeds"| node_postgres

click node_web "https://github.com/zedzed34/agnos-backend/blob/main/web/app.js"
click node_entry "https://github.com/zedzed34/agnos-backend/blob/main/cmd/api/main.go"
click node_authhandler "https://github.com/zedzed34/agnos-backend/blob/main/internal/handler/auth_handler.go"
click node_patienthandler "https://github.com/zedzed34/agnos-backend/blob/main/internal/handler/patient_handler.go"
click node_middleware "https://github.com/zedzed34/agnos-backend/blob/main/internal/middleware/auth_middleware.go"
click node_authservice "https://github.com/zedzed34/agnos-backend/blob/main/internal/service/auth_service.go"
click node_patientservice "https://github.com/zedzed34/agnos-backend/blob/main/internal/service/patient_service.go"
click node_domain "https://github.com/zedzed34/agnos-backend/blob/main/internal/domain/patient.go"
click node_config "https://github.com/zedzed34/agnos-backend/blob/main/config/config.go"
click node_hospitalrepo "https://github.com/zedzed34/agnos-backend/blob/main/internal/repository/hospital_repo.go"
click node_staffrepo "https://github.com/zedzed34/agnos-backend/blob/main/internal/repository/staff_repo.go"
click node_patientrepo "https://github.com/zedzed34/agnos-backend/blob/main/internal/repository/patient_repo.go"
click node_hospitalclient "https://github.com/zedzed34/agnos-backend/blob/main/internal/infrastructure/hospital_client.go"

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_staff,node_web toneBlue
class node_entry,node_authhandler,node_patienthandler,node_middleware,node_config toneAmber
class node_authservice,node_patientservice,node_domain toneMint
class node_hospitalrepo,node_staffrepo,node_patientrepo,node_hospitalclient,node_postgres,node_hospitalapi toneRose
```

## Components

### Staff client

- **Hospital staff**
- [Web interface](https://github.com/zedzed34/agnos-backend/blob/main/web/app.js): `web/app.js`

### HTTP API

- [API entrypoint](https://github.com/zedzed34/agnos-backend/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Auth handlers](https://github.com/zedzed34/agnos-backend/blob/main/internal/handler/auth_handler.go): `internal/handler/auth_handler.go`
- [Patient handler](https://github.com/zedzed34/agnos-backend/blob/main/internal/handler/patient_handler.go): `internal/handler/patient_handler.go`
- [JWT middleware](https://github.com/zedzed34/agnos-backend/blob/main/internal/middleware/auth_middleware.go): `internal/middleware/auth_middleware.go`
- [Runtime config](https://github.com/zedzed34/agnos-backend/blob/main/config/config.go): `config/config.go`

### Domain services

- [Authentication](https://github.com/zedzed34/agnos-backend/blob/main/internal/service/auth_service.go): `internal/service/auth_service.go`
- [Patient search](https://github.com/zedzed34/agnos-backend/blob/main/internal/service/patient_service.go): `internal/service/patient_service.go`
- [Domain models](https://github.com/zedzed34/agnos-backend/blob/main/internal/domain/patient.go): `internal/domain/patient.go`

### Persistence and integrations

- [Hospital repository](https://github.com/zedzed34/agnos-backend/blob/main/internal/repository/hospital_repo.go): `internal/repository/hospital_repo.go`
- [Staff repository](https://github.com/zedzed34/agnos-backend/blob/main/internal/repository/staff_repo.go): `internal/repository/staff_repo.go`
- [Patient repository](https://github.com/zedzed34/agnos-backend/blob/main/internal/repository/patient_repo.go): `internal/repository/patient_repo.go`
- [Hospital API client](https://github.com/zedzed34/agnos-backend/blob/main/internal/infrastructure/hospital_client.go): `internal/infrastructure/hospital_client.go`
- **PostgreSQL**
- **Hospital A API**

## Connections

- Hospital staff → Web interface: uses
- Web interface → API entrypoint: requests pages
- Web interface → Auth handlers: registers / logs in
- Web interface → Patient handler: searches patients
- API entrypoint → Runtime config: loads settings
- API entrypoint → Auth handlers: routes auth
- API entrypoint → JWT middleware: protects search
- API entrypoint → Patient handler: routes search
- Auth handlers → Authentication: calls
- Authentication → Hospital repository: finds hospital
- Authentication → Staff repository: creates / finds staff
- Patient handler → JWT middleware: reads hospital claim
- Patient handler → Patient search: passes filters
- Patient search → Patient repository: searches locally
- Patient search → Hospital API client: fetches on fallback
- Patient search → Patient repository: caches result
- Hospital API client → Hospital A API: requests patient
- Hospital repository → PostgreSQL: reads hospitals
- Staff repository → PostgreSQL: reads / writes staff
- Patient repository → PostgreSQL: reads / upserts patients
- API entrypoint → PostgreSQL: migrates / seeds