# pro158127/gastro-ai architecture

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

- Interactive diagram: https://gitdiagram.com/pro158127/gastro-ai
- Repository: https://github.com/pro158127/gastro-ai

## Overview

Gastro-AI is a clinical-image analysis application with JWT login, asynchronous analysis, and live result updates. A doctor signs in, uploads an image with patient-document details, and receives a processing record; a Celery task performs the scaffold’s stub inference, creates a Grad-CAM placeholder, requests an LLM explanation, persists the result, and publishes completion for the dashboard to retrieve and display. The README also documents polling as an alternative to WebSockets. AI integrations are currently stubs; unsampled modules are represented only where documented, so some links rely on README evidence.

Main entry points: [`backend/app/tasks.py`](https://github.com/pro158127/gastro-ai/blob/main/backend/app/tasks.py) (Analysis task), [`backend/app/services/analisis_service.py`](https://github.com/pro158127/gastro-ai/blob/main/backend/app/services/analisis_service.py) (Analysis service), [`backend/app/main.py`](https://github.com/pro158127/gastro-ai/blob/main/backend/app/main.py) (FastAPI entry), [`frontend/src/pages/Dashboard.tsx`](https://github.com/pro158127/gastro-ai/blob/main/frontend/src/pages/Dashboard.tsx) (Analysis dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routing<br/>[App.tsx]"]
  node_login["Login page<br/>[Login.tsx]"]
  node_dashboard["Analysis dashboard<br/>[Dashboard.tsx]"]
  node_httpclient["HTTP API client<br/>[api.ts]"]
  node_wsclient["WebSocket client<br/>[websocket.ts]"]
end

subgraph group_api["API and identity"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_security["JWT security<br/>[security.py]"]
  node_analysis_routes["Analysis routes<br/>[analisis.py]"]
  node_ws_routes["WebSocket routes<br/>[ws.py]"]
end

subgraph group_processing["Analysis processing"]
  node_analysis_service["Analysis service"]
  node_worker_task["Analysis task<br/>[tasks.py]"]
  node_celery["Celery worker<br/>[worker.py]"]
end

subgraph group_infra["Persistence and messaging"]
  node_database[("PostgreSQL")]
  node_redis[("Redis")]
  node_minio[("MinIO object store")]
  node_models["ORM models<br/>[analisis.py]"]
end

subgraph group_integrations["AI and object storage"]
  node_llm["LLM adapter<br/>[llm_adapter.py]"]
  node_minio_adapter["MinIO adapter<br/>[minio_adapter.py]"]
end

node_doctor(("Doctor / Admin"))
node_gateway["Nginx gateway<br/>[nginx.conf]"]

node_doctor -->|"uses web"| node_gateway
node_gateway -->|"serves SPA"| node_app
node_gateway -->|"proxies API"| node_api_entry
node_gateway -->|"proxies WebSocket"| node_ws_routes
node_app -->|"renders"| node_login
node_app -->|"renders"| node_dashboard
node_login -->|"calls"| node_httpclient
node_dashboard -->|"calls"| node_httpclient
node_dashboard -->|"subscribes"| node_wsclient
node_httpclient -->|"sends HTTP"| node_api_entry
node_wsclient -->|"connects"| node_ws_routes
node_api_entry -->|"mounts routes"| node_auth
node_api_entry -->|"mounts routes"| node_analysis_routes
node_api_entry -->|"mounts routes"| node_ws_routes
node_auth -->|"queries users"| node_database
node_auth -->|"verifies and signs"| node_security
node_analysis_routes -->|"delegates"| node_analysis_service
node_analysis_service -->|"stores image"| node_minio_adapter
node_analysis_service -->|"creates and reads"| node_database
node_analysis_service -->|"enqueues"| node_worker_task
node_analysis_service -->|"uses model"| node_models
node_worker_task -->|"uses app"| node_celery
node_worker_task -->|"stores Grad-CAM"| node_minio_adapter
node_worker_task -->|"requests explanation"| node_llm
node_worker_task -->|"updates result"| node_database
node_worker_task -->|"publishes event"| node_redis
node_ws_routes -->|"forwards events"| node_redis
node_minio_adapter -->|"reads and writes"| node_minio
node_analysis_routes -->|"uses session"| node_database
node_analysis_routes -->|"uses model"| node_models
node_dashboard -.->|"polls status"| node_httpclient

click node_app "https://github.com/pro158127/gastro-ai/blob/main/frontend/src/App.tsx"
click node_login "https://github.com/pro158127/gastro-ai/blob/main/frontend/src/pages/Login.tsx"
click node_dashboard "https://github.com/pro158127/gastro-ai/blob/main/frontend/src/pages/Dashboard.tsx"
click node_httpclient "https://github.com/pro158127/gastro-ai/blob/main/frontend/src/services/api.ts"
click node_wsclient "https://github.com/pro158127/gastro-ai/blob/main/frontend/src/services/websocket.ts"
click node_gateway "https://github.com/pro158127/gastro-ai/blob/main/nginx.conf"
click node_api_entry "https://github.com/pro158127/gastro-ai/blob/main/backend/app/main.py"
click node_auth "https://github.com/pro158127/gastro-ai/blob/main/backend/app/routers/auth.py"
click node_security "https://github.com/pro158127/gastro-ai/blob/main/backend/app/security.py"
click node_analysis_routes "https://github.com/pro158127/gastro-ai/blob/main/backend/app/routers/analisis.py"
click node_analysis_service "https://github.com/pro158127/gastro-ai/blob/main/backend/app/services/analisis_service.py"
click node_worker_task "https://github.com/pro158127/gastro-ai/blob/main/backend/app/tasks.py"
click node_celery "https://github.com/pro158127/gastro-ai/blob/main/backend/app/worker.py"
click node_llm "https://github.com/pro158127/gastro-ai/blob/main/backend/app/adapters/llm_adapter.py"
click node_minio_adapter "https://github.com/pro158127/gastro-ai/blob/main/backend/app/adapters/minio_adapter.py"
click node_ws_routes "https://github.com/pro158127/gastro-ai/blob/main/backend/app/routers/ws.py"
click node_models "https://github.com/pro158127/gastro-ai/blob/main/backend/app/models/analisis.py"

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_app,node_login,node_dashboard,node_httpclient,node_wsclient toneBlue
class node_api_entry,node_auth,node_security,node_analysis_routes,node_ws_routes toneAmber
class node_analysis_service,node_worker_task,node_celery toneMint
class node_database,node_redis,node_minio,node_models toneRose
class node_llm,node_minio_adapter,node_doctor toneIndigo
class node_gateway toneTeal
```

## Components

### Web client

- [App routing](https://github.com/pro158127/gastro-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login page](https://github.com/pro158127/gastro-ai/blob/main/frontend/src/pages/Login.tsx): `frontend/src/pages/Login.tsx`
- [Analysis dashboard](https://github.com/pro158127/gastro-ai/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [HTTP API client](https://github.com/pro158127/gastro-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [WebSocket client](https://github.com/pro158127/gastro-ai/blob/main/frontend/src/services/websocket.ts): `frontend/src/services/websocket.ts`

### API and identity

- [FastAPI entry](https://github.com/pro158127/gastro-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/pro158127/gastro-ai/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [JWT security](https://github.com/pro158127/gastro-ai/blob/main/backend/app/security.py): `backend/app/security.py`
- [Analysis routes](https://github.com/pro158127/gastro-ai/blob/main/backend/app/routers/analisis.py): `backend/app/routers/analisis.py`
- [WebSocket routes](https://github.com/pro158127/gastro-ai/blob/main/backend/app/routers/ws.py): `backend/app/routers/ws.py`

### Analysis processing

- [Analysis service](https://github.com/pro158127/gastro-ai/blob/main/backend/app/services/analisis_service.py): `backend/app/services/analisis_service.py`
- [Analysis task](https://github.com/pro158127/gastro-ai/blob/main/backend/app/tasks.py): `backend/app/tasks.py`
- [Celery worker](https://github.com/pro158127/gastro-ai/blob/main/backend/app/worker.py): `backend/app/worker.py`

### Persistence and messaging

- **PostgreSQL**
- **Redis**
- **MinIO object store**
- [ORM models](https://github.com/pro158127/gastro-ai/blob/main/backend/app/models/analisis.py): `backend/app/models/analisis.py`

### AI and object storage

- [LLM adapter](https://github.com/pro158127/gastro-ai/blob/main/backend/app/adapters/llm_adapter.py): `backend/app/adapters/llm_adapter.py`
- [MinIO adapter](https://github.com/pro158127/gastro-ai/blob/main/backend/app/adapters/minio_adapter.py): `backend/app/adapters/minio_adapter.py`

### Other components

- **Doctor / Admin**
- [Nginx gateway](https://github.com/pro158127/gastro-ai/blob/main/nginx.conf): `nginx.conf`

## Connections

- Doctor / Admin → Nginx gateway: uses web (evidence: `README.md`)
- Nginx gateway → App routing: serves SPA (evidence: `README.md`)
- Nginx gateway → FastAPI entry: proxies API (evidence: `README.md`)
- Nginx gateway → WebSocket routes: proxies WebSocket (evidence: `README.md`)
- App routing → Login page: renders (evidence: `frontend/src/App.tsx`)
- App routing → Analysis dashboard: renders (evidence: `frontend/src/App.tsx`)
- Login page → HTTP API client: calls (evidence: `frontend/src/pages/Login.tsx`)
- Analysis dashboard → HTTP API client: calls (evidence: `frontend/src/pages/Dashboard.tsx`)
- Analysis dashboard → WebSocket client: subscribes (evidence: `frontend/src/pages/Dashboard.tsx`)
- HTTP API client → FastAPI entry: sends HTTP (evidence: `README.md`)
- WebSocket client → WebSocket routes: connects (evidence: `README.md`)
- FastAPI entry → Authentication routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI entry → Analysis routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI entry → WebSocket routes: mounts routes (evidence: `backend/app/main.py`)
- Authentication routes → PostgreSQL: queries users (evidence: `backend/app/routers/auth.py`)
- Authentication routes → JWT security: verifies and signs (evidence: `backend/app/routers/auth.py`)
- Analysis routes → Analysis service: delegates (evidence: `backend/app/routers/analisis.py`)
- Analysis service → MinIO adapter: stores image (evidence: `backend/app/services/analisis_service.py`)
- Analysis service → PostgreSQL: creates and reads (evidence: `backend/app/services/analisis_service.py`)
- Analysis service → Analysis task: enqueues (evidence: `backend/app/services/analisis_service.py`)
- Analysis service → ORM models: uses model (evidence: `backend/app/services/analisis_service.py`)
- Analysis task → Celery worker: uses app (evidence: `backend/app/tasks.py`)
- Analysis task → MinIO adapter: stores Grad-CAM (evidence: `backend/app/tasks.py`)
- Analysis task → LLM adapter: requests explanation (evidence: `backend/app/tasks.py`)
- Analysis task → PostgreSQL: updates result (evidence: `backend/app/tasks.py`)
- Analysis task → Redis: publishes event (evidence: `backend/app/tasks.py`)
- WebSocket routes → Redis: forwards events (evidence: `README.md`)
- MinIO adapter → MinIO object store: reads and writes (evidence: `backend/app/adapters/minio_adapter.py`)
- Analysis routes → PostgreSQL: uses session (evidence: `backend/app/routers/analisis.py`)
- Analysis routes → ORM models: uses model (evidence: `backend/app/routers/analisis.py`)
- Analysis dashboard → HTTP API client: polls status (evidence: `README.md`)