# itevolution-usc/gastro-sim architecture

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

- Interactive diagram: https://gitdiagram.com/itevolution-usc/gastro-sim
- Repository: https://github.com/itevolution-usc/gastro-sim

## Overview

GASTRO-SIM is an academic web-based 3D simulator for practicing human–AI decision-making in gastrointestinal endoscopy. The documented learner flow requests an AI-generated case, explores anatomy and captures a finding, records an initial decision, reviews a vision-AI recommendation and optional tutor guidance, then submits a final decision and receives feedback; attempts support evaluation of learner behavior. The checked-in runtime is currently an API scaffold: it starts FastAPI, configures connections and errors, and exposes health and public catalog endpoints. The broader workflow is documented in the README, not implemented in the sampled source.

Main entry points: [`api/app/main.py`](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/main.py) (FastAPI API), [`api/app/db.py`](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/db.py) (Connection pool), [`api/app/routers/salud.py`](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/routers/salud.py) (Health and catalogs), [`README.md`](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md) (AI case generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API Runtime"]
  node_api["FastAPI API<br/>[main.py]"]
  node_settings["Configuration<br/>[config.py]"]
  node_errors["Error handlers<br/>[errores.py]"]
  node_health["Health and catalogs<br/>[salud.py]"]
end

subgraph group_simulation["Clinical Simulation"]
  node_case["AI case generation<br/>[README.md]"]
  node_image["Public endoscopy image<br/>[README.md]"]
  node_exploration["3D endoscopy<br/>[README.md]"]
  node_finding["Finding capture<br/>[README.md]"]
end

subgraph group_decision["Decision Training"]
  node_initial["Initial decision<br/>[README.md]"]
  node_vision["Vision recommendation<br/>[README.md]"]
  node_tutor["AI tutor<br/>[README.md]"]
  node_final["Final decision<br/>[README.md]"]
  node_feedback["Learning feedback<br/>[README.md]"]
  node_attempts[("Attempt tracking<br/>[README.md]")]
end

subgraph group_persistence["Platform Data"]
  node_pool["Connection pool<br/>[db.py]"]
  node_database[("PostgreSQL schema")]
end

node_student(("Student"))

node_student -->|"requests case"| node_case
node_case -->|"uses image"| node_image
node_student -->|"explores anatomy"| node_exploration
node_exploration -->|"captures finding"| node_finding
node_student -->|"records decision"| node_initial
node_initial -->|"reviews recommendation"| node_vision
node_student -.->|"may consult"| node_tutor
node_student -->|"records decision"| node_final
node_final -->|"receives feedback"| node_feedback
node_attempts -->|"supports evaluation"| node_feedback
node_api -->|"loads settings"| node_settings
node_api -->|"opens and closes"| node_pool
node_api -->|"registers handlers"| node_errors
node_api -->|"mounts router"| node_health
node_health -->|"queries through"| node_pool
node_pool -.->|"connects to"| node_database

click node_api "https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/main.py"
click node_settings "https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/config.py"
click node_errors "https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/errores.py"
click node_health "https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/routers/salud.py"
click node_pool "https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/db.py"
click node_database "https://github.com/itevolution-usc/gastro-sim/blob/main/db/migraciones/001_esquema_inicial.sql"
click node_case "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_image "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_exploration "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_finding "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_initial "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_vision "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_tutor "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_final "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_feedback "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"
click node_attempts "https://github.com/itevolution-usc/gastro-sim/blob/main/README.md"

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_api,node_settings,node_errors,node_health toneBlue
class node_case,node_image,node_exploration,node_finding toneAmber
class node_initial,node_vision,node_tutor,node_final,node_feedback,node_attempts toneMint
class node_pool,node_database toneRose
class node_student toneIndigo
```

## Components

### API Runtime

- [FastAPI API](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/main.py): `api/app/main.py`
- [Configuration](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/config.py): `api/app/config.py`
- [Error handlers](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/errores.py): `api/app/errores.py`
- [Health and catalogs](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/routers/salud.py): `api/app/routers/salud.py`

### Clinical Simulation

- [AI case generation](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [Public endoscopy image](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [3D endoscopy](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [Finding capture](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`

### Decision Training

- [Initial decision](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [Vision recommendation](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [AI tutor](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [Final decision](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [Learning feedback](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`
- [Attempt tracking](https://github.com/itevolution-usc/gastro-sim/blob/main/README.md): `README.md`

### Platform Data

- [Connection pool](https://github.com/itevolution-usc/gastro-sim/blob/main/api/app/db.py): `api/app/db.py`
- [PostgreSQL schema](https://github.com/itevolution-usc/gastro-sim/blob/main/db/migraciones/001_esquema_inicial.sql): `db/migraciones/001_esquema_inicial.sql`

### Other components

- **Student**

## Connections

- Student → AI case generation: requests case (evidence: `README.md`)
- AI case generation → Public endoscopy image: uses image (evidence: `README.md`)
- Student → 3D endoscopy: explores anatomy (evidence: `README.md`)
- 3D endoscopy → Finding capture: captures finding (evidence: `README.md`)
- Student → Initial decision: records decision (evidence: `README.md`)
- Initial decision → Vision recommendation: reviews recommendation (evidence: `README.md`)
- Student → AI tutor: may consult (evidence: `README.md`)
- Student → Final decision: records decision (evidence: `README.md`)
- Final decision → Learning feedback: receives feedback (evidence: `README.md`)
- Attempt tracking → Learning feedback: supports evaluation (evidence: `README.md`)
- FastAPI API → Configuration: loads settings (evidence: `api/app/main.py`)
- FastAPI API → Connection pool: opens and closes (evidence: `api/app/main.py`)
- FastAPI API → Error handlers: registers handlers (evidence: `api/app/main.py`)
- FastAPI API → Health and catalogs: mounts router (evidence: `api/app/main.py`)
- Health and catalogs → Connection pool: queries through (evidence: `api/app/routers/salud.py`)
- Connection pool → PostgreSQL schema: connects to