agasthya736/lucidia

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.