# agasthya736/lucidia architecture

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

- Interactive diagram: https://gitdiagram.com/agasthya736/lucidia
- Repository: https://github.com/agasthya736/lucidia

## Overview

#### Purpose and entry points
Lucidia/VeriRad is an early-stage CT-scan documentation and second-read support system. It accepts scans, coordinates multiple AI readers into a report draft, and preserves clinician review as the final decision boundary. Main runtime entry points are the Spring Boot service at `backend/src/main/java/com/lucidia/backend/LucidiaApplication.java` and Flutter client at `mobile/lib/main.dart`.

#### Client application
The cross-platform Flutter client provides authentication, scan capture/submission, pipeline status, and report viewing. Its application-level API boundary is `mobile/lib/shared/api_client.dart`; scan workflows are centered in `mobile/lib/scan/scan_capture_screen.dart` and `mobile/lib/scan/scan_service.dart`. Authentication UI and token-facing behavior reside under `mobile/lib/auth/auth_service.dart`.

#### Backend API and security boundary
Spring Boot exposes scan and diagnostic/test endpoints through `backend/src/main/java/com/lucidia/backend/api/ScanController.java` and `backend/src/main/java/com/lucidia/backend/api/VisionTestController.java`. Authentication is a separate API/domain boundary at `backend/src/main/java/com/lucidia/backend/auth/AuthController.java`, with JWT handling in `backend/src/main/java/com/lucidia/backend/auth/JwtService.java` and authorization policy in `backend/src/main/java/com/lucidia/backend/config/SecurityConfig.java`. DTOs isolate HTTP payloads from internal models in `backend/src/main/java/com/lucidia/backend/dto/ScanDtos.java`.

#### Scan lifecycle and persistence
`backend/src/main/java/com/lucidia/backend/scan/ScanService.java` owns scan-oriented application behavior, backed by JPA persistence via `backend/src/main/java/com/lucidia/backend/scan/Scan.java` and `backend/src/main/java/com/lucidia/backend/scan/ScanRepository.java`. Uploaded image binaries are held behind `backend/src/main/java/com/lucidia/backend/scan/ImageStorageService.java`, currently reflected by local vault-like content in `backend/data/images`. Generated report delivery is separated into `backend/src/main/java/com/lucidia/backend/scan/ReportPdfService.java`.

#### Multi-agent pipeline orchestration
`backend/src/main/java/com/lucidia/backend/orchestrator/PipelineOrchestrator.java` is the primary control-flow coordinator. It returns a normalized outcome through `backend/src/main/java/com/lucidia/backend/orchestrator/PipelineResult.java` and surfaces unrecoverable execution through `backend/src/main/java/com/lucidia/backend/orchestrator/PipelineFailedException.java`. Retry semantics are centralized in `backend/src/main/java/com/lucidia/backend/agents/RetryHelper.java`, establishing a resilience boundary around model/service calls.

#### AI stages and provider boundary
Independent image interpretation is abstracted by `backend/src/main/java/com/lucidia/backend/agents/vision/VisionAgent.java`, with provider implementations for Gemini and Ollama in `backend/src/main/java/com/lucidia/backend/agents/vision/GeminiVisionAgent.java` and `backend/src/main/java/com/lucidia/backend/agents/vision/OllamaVisionAgent.java`. Findings are normalized through `backend/src/main/java/com/lucidia/backend/agents/vision/VisionFindings.java`. Consensus is handled by `backend/src/main/java/com/lucidia/backend/agents/arbiter/ArbiterAgent.java`; report drafting by `backend/src/main/java/com/lucidia/backend/agents/writing/WritingAgent.java`; and claim checking by `backend/src/main/java/com/lucidia/backend/agents/verifier/VerifierAgent.java`. Implementations are scaffold-level, so these interfaces are the key extension points.

#### Explainability and external infrastructure
A dedicated Python service supplies MedSAM-based image analysis/explainability: `medsam-service/app.py`, containerized by `medsam-service/Dockerfile`. Java reaches it through `backend/src/main/java/com/lucidia/backend/agents/vision/MedSamClient.java` and carries output in `backend/src/main/java/com/lucidia/backend/agents/vision/MedSamFindings.java`. The system also depends on PostgreSQL, with schema evolution in `backend/src/main/resources/db/migration`, and external LLM/model-provider APIs configured in `backend/src/main/resources/application.yml`. Root `docker-compose.yml` is the infrastructure composition point.

#### Audit and review accountability
The backend records traceable audit events through `backend/src/main/java/com/lucidia/backend/audit/AuditLogService.java`, persisted as `backend/src/main/java/com/lucidia/backend/audit/AuditLogEntry.java`. This supports the core operational boundary: AI outputs are drafts/supporting evidence, while clinician review and sign-off remain outside automated diagnostic authority.

Main entry points: [`backend/src/main/java/com/lucidia/backend/scan/ScanService.java`](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ScanService.java) (Scan lifecycle), [`backend/src/main/java/com/lucidia/backend/orchestrator/PipelineOrchestrator.java`](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/orchestrator/PipelineOrchestrator.java) (Pipeline orchestrator), [`mobile/lib/shared/api_client.dart`](https://github.com/agasthya736/lucidia/blob/main/mobile/lib/shared/api_client.dart) (API client), [`backend/src/main/java/com/lucidia/backend/config/SecurityConfig.java`](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/config/SecurityConfig.java) (JWT security policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter Client"]
  node_mobile_app["Flutter application<br/>client runtime<br/>[main.dart]"]
  node_mobile_api["API client<br/>HTTP boundary<br/>[api_client.dart]"]
  node_scan_capture["Scan capture<br/>client workflow"]
  node_auth_ui["Auth service<br/>client auth<br/>[auth_service.dart]"]
end

subgraph group_backend["Spring Backend"]
  node_security["JWT security policy<br/>security boundary"]
  node_auth_api["Authentication API<br/>auth controller"]
  node_jwt["JWT service<br/>token service<br/>[JwtService.java]"]
  node_scan_api["Scan API<br/>REST controller"]
  node_scan_service["Scan lifecycle<br/>application service<br/>[ScanService.java]"]
  node_scan_store[("Scan persistence<br/>JPA repository")]
  node_image_storage[("Image storage<br/>binary storage")]
  node_report_pdf["Report PDF delivery<br/>report service"]
  node_audit["Audit logging<br/>accountability service"]
end

subgraph group_ai["AI Pipeline"]
  node_orchestrator["Pipeline orchestrator<br/>workflow coordinator"]
  node_vision_agents["Vision readers<br/>provider abstraction<br/>[VisionAgent.java]"]
  node_medsam_client["MedSAM client<br/>explainability adapter<br/>[MedSamClient.java]"]
  node_arbiter["Consensus arbiter<br/>AI stage<br/>[ArbiterAgent.java]"]
  node_writer["Report writer<br/>AI stage<br/>[WritingAgent.java]"]
  node_verifier["Claim verifier<br/>AI stage<br/>[VerifierAgent.java]"]
end

subgraph group_infra["External Infrastructure"]
  node_providers{{"LLM provider APIs<br/>external model APIs<br/>[application.yml]"}}
  node_medsam["MedSAM service<br/>Python analysis service<br/>[app.py]"]
  node_postgres[("PostgreSQL<br/>database")]
end

node_clinician(("Clinician review<br/>human decision boundary"))

node_mobile_app -->|"uses"| node_mobile_api
node_scan_capture -->|"submits scans"| node_mobile_api
node_auth_ui -->|"authenticates"| node_mobile_api
node_mobile_api -->|"authenticated requests"| node_security
node_security -->|"protects"| node_auth_api
node_auth_api -->|"issues tokens"| node_jwt
node_security -->|"authorizes"| node_scan_api
node_scan_api -->|"scan requests"| node_scan_service
node_scan_service -->|"persists metadata"| node_scan_store
node_scan_service -->|"stores images"| node_image_storage
node_scan_service -->|"starts analysis"| node_orchestrator
node_orchestrator -->|"independent reads"| node_vision_agents
node_vision_agents -->|"model calls"| node_providers
node_orchestrator -->|"requests explainability"| node_medsam_client
node_medsam_client -->|"analysis request"| node_medsam
node_orchestrator -->|"reconciles findings"| node_arbiter
node_arbiter -->|"consensus"| node_writer
node_writer -->|"draft claims"| node_verifier
node_verifier -->|"verified draft"| node_scan_service
node_scan_service -->|"generates report"| node_report_pdf
node_scan_service -->|"records events"| node_audit
node_scan_store -->|"JPA data"| node_postgres
node_audit -->|"audit records"| node_postgres
node_report_pdf -->|"draft for review"| node_clinician

click node_mobile_app "https://github.com/agasthya736/lucidia/blob/main/mobile/lib/main.dart"
click node_mobile_api "https://github.com/agasthya736/lucidia/blob/main/mobile/lib/shared/api_client.dart"
click node_scan_capture "https://github.com/agasthya736/lucidia/blob/main/mobile/lib/scan/scan_capture_screen.dart"
click node_auth_ui "https://github.com/agasthya736/lucidia/blob/main/mobile/lib/auth/auth_service.dart"
click node_security "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/config/SecurityConfig.java"
click node_auth_api "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/auth/AuthController.java"
click node_jwt "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/auth/JwtService.java"
click node_scan_api "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/api/ScanController.java"
click node_scan_service "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ScanService.java"
click node_scan_store "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ScanRepository.java"
click node_image_storage "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ImageStorageService.java"
click node_report_pdf "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ReportPdfService.java"
click node_audit "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/audit/AuditLogService.java"
click node_orchestrator "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/orchestrator/PipelineOrchestrator.java"
click node_vision_agents "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/vision/VisionAgent.java"
click node_medsam_client "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/vision/MedSamClient.java"
click node_arbiter "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/arbiter/ArbiterAgent.java"
click node_writer "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/writing/WritingAgent.java"
click node_verifier "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/verifier/VerifierAgent.java"
click node_providers "https://github.com/agasthya736/lucidia/blob/main/backend/src/main/resources/application.yml"
click node_medsam "https://github.com/agasthya736/lucidia/blob/main/medsam-service/app.py"
click node_postgres "https://github.com/agasthya736/lucidia/tree/main/backend/src/main/resources/db/migration"

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_mobile_app,node_mobile_api,node_scan_capture,node_auth_ui toneBlue
class node_security,node_auth_api,node_jwt,node_scan_api,node_scan_service,node_scan_store,node_image_storage,node_report_pdf,node_audit toneAmber
class node_orchestrator,node_vision_agents,node_medsam_client,node_arbiter,node_writer,node_verifier toneMint
class node_providers,node_medsam,node_postgres toneRose
class node_clinician toneNeutral
```

## Components

### Flutter Client

- [Flutter application](https://github.com/agasthya736/lucidia/blob/main/mobile/lib/main.dart): client runtime · Authentication, scan submission, status, and report viewing. · `mobile/lib/main.dart`
- [API client](https://github.com/agasthya736/lucidia/blob/main/mobile/lib/shared/api_client.dart): HTTP boundary · `mobile/lib/shared/api_client.dart`
- [Scan capture](https://github.com/agasthya736/lucidia/blob/main/mobile/lib/scan/scan_capture_screen.dart): client workflow · `mobile/lib/scan/scan_capture_screen.dart`
- [Auth service](https://github.com/agasthya736/lucidia/blob/main/mobile/lib/auth/auth_service.dart): client auth · `mobile/lib/auth/auth_service.dart`

### Spring Backend

- [JWT security policy](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/config/SecurityConfig.java): security boundary · `backend/src/main/java/com/lucidia/backend/config/SecurityConfig.java`
- [Authentication API](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/auth/AuthController.java): auth controller · `backend/src/main/java/com/lucidia/backend/auth/AuthController.java`
- [JWT service](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/auth/JwtService.java): token service · `backend/src/main/java/com/lucidia/backend/auth/JwtService.java`
- [Scan API](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/api/ScanController.java): REST controller · `backend/src/main/java/com/lucidia/backend/api/ScanController.java`
- [Scan lifecycle](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ScanService.java): application service · `backend/src/main/java/com/lucidia/backend/scan/ScanService.java`
- [Scan persistence](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ScanRepository.java): JPA repository · `backend/src/main/java/com/lucidia/backend/scan/ScanRepository.java`
- [Image storage](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ImageStorageService.java): binary storage · Local vault-like image content. · `backend/src/main/java/com/lucidia/backend/scan/ImageStorageService.java`
- [Report PDF delivery](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/scan/ReportPdfService.java): report service · `backend/src/main/java/com/lucidia/backend/scan/ReportPdfService.java`
- [Audit logging](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/audit/AuditLogService.java): accountability service · Records traceable AI and workflow events. · `backend/src/main/java/com/lucidia/backend/audit/AuditLogService.java`

### AI Pipeline

- [Pipeline orchestrator](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/orchestrator/PipelineOrchestrator.java): workflow coordinator · Coordinates AI readers and normalizes pipeline outcomes. · `backend/src/main/java/com/lucidia/backend/orchestrator/PipelineOrchestrator.java`
- [Vision readers](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/vision/VisionAgent.java): provider abstraction · Gemini and Ollama implementations produce normalized findings. · `backend/src/main/java/com/lucidia/backend/agents/vision/VisionAgent.java`
- [MedSAM client](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/vision/MedSamClient.java): explainability adapter · `backend/src/main/java/com/lucidia/backend/agents/vision/MedSamClient.java`
- [Consensus arbiter](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/arbiter/ArbiterAgent.java): AI stage · `backend/src/main/java/com/lucidia/backend/agents/arbiter/ArbiterAgent.java`
- [Report writer](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/writing/WritingAgent.java): AI stage · `backend/src/main/java/com/lucidia/backend/agents/writing/WritingAgent.java`
- [Claim verifier](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/java/com/lucidia/backend/agents/verifier/VerifierAgent.java): AI stage · `backend/src/main/java/com/lucidia/backend/agents/verifier/VerifierAgent.java`

### External Infrastructure

- [LLM provider APIs](https://github.com/agasthya736/lucidia/blob/main/backend/src/main/resources/application.yml): external model APIs · `backend/src/main/resources/application.yml`
- [MedSAM service](https://github.com/agasthya736/lucidia/blob/main/medsam-service/app.py): Python analysis service · Containerized image analysis and explainability service. · `medsam-service/app.py`
- [PostgreSQL](https://github.com/agasthya736/lucidia/tree/main/backend/src/main/resources/db/migration): database · Stores scans and audit records. · `backend/src/main/resources/db/migration`

### Other components

- **Clinician review**: human decision boundary · Final sign-off remains outside automated diagnostic authority.

## Connections

- Flutter application → API client: uses
- Scan capture → API client: submits scans
- Auth service → API client: authenticates
- API client → JWT security policy: authenticated requests
- JWT security policy → Authentication API: protects
- Authentication API → JWT service: issues tokens
- JWT security policy → Scan API: authorizes
- Scan API → Scan lifecycle: scan requests
- Scan lifecycle → Scan persistence: persists metadata
- Scan lifecycle → Image storage: stores images
- Scan lifecycle → Pipeline orchestrator: starts analysis
- Pipeline orchestrator → Vision readers: independent reads
- Vision readers → LLM provider APIs: model calls
- Pipeline orchestrator → MedSAM client: requests explainability
- MedSAM client → MedSAM service: analysis request
- Pipeline orchestrator → Consensus arbiter: reconciles findings
- Consensus arbiter → Report writer: consensus
- Report writer → Claim verifier: draft claims
- Claim verifier → Scan lifecycle: verified draft
- Scan lifecycle → Report PDF delivery: generates report
- Scan lifecycle → Audit logging: records events
- Scan persistence → PostgreSQL: JPA data
- Audit logging → PostgreSQL: audit records
- Report PDF delivery → Clinician review: draft for review