# adityacodes-root/oculusai architecture

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

- Interactive diagram: https://gitdiagram.com/adityacodes-root/oculusai
- Repository: https://github.com/adityacodes-root/oculusai

## Overview

1. **Overall shape**
   OculusAI is a two-tier ML application: a **Next.js/React frontend** for user interaction and a **Python/Flask backend** for AI inference and image validation. A separate **Streamlit app** exists as an alternate UI for retina analysis, but the main product boundary is frontend → API → model inference.

2. **User-facing frontend**
   The `frontend/` directory is a Next.js 16 app with pages for **home, analyze, colorblindness, diseases, evaluation, and about**. It acts as the presentation layer: image upload, interactive Ishihara test flow, result visualization, theme switching, mobile navigation, and report downloads. The UI is built from reusable components and shadcn/ui-style primitives.

3. **Frontend responsibilities vs backend responsibilities**
   The frontend does not appear to run ML locally; instead it calls the Flask API configured via `frontend/.env.local` using `NEXT_PUBLIC_API_URL`. It also generates PDF artifacts on the client side through dedicated report components, so report composition is split between UI rendering and backend model output.

4. **Backend API layer**
   `flask_app.py` is the central server for programmatic access. Based on the README, it handles **image validation**, **retinal disease classification**, and **Ishihara digit recognition / color blindness diagnosis**. This is the main service boundary that both the Next.js app and any external clients would integrate with.

5. **ML inference subsystems**
   There are two distinct deep-learning pipelines:
   - **Retinal disease classifier** for cataract, diabetic retinopathy, glaucoma, or normal
   - **Color vision / Ishihara classifier** for digit recognition and Deutan/Protan assessment
   They are separate models with different input sizes and behavior, but both are exposed through the same backend service.

6. **Domain data flow: retinal analysis**
   For retinal images, the flow is: user upload or sample selection → frontend sends image to Flask → backend validates that the image looks like a fundus photo → model inference → frontend renders class probabilities/summary and can produce a PDF report. Sample retinal images are stored under `Sample_Retinal_Images/` and exposed in the UI under `frontend/public/samples/`.

7. **Domain data flow: color blindness test**
   The Ishihara flow is interactive rather than one-shot upload: the frontend presents a 40-plate test using `CBTestImages/`, records responses, and submits/derives recognition results. The backend/model identifies the plate digits and determines likely color deficiency type and severity, while the frontend handles progress, mobile number-pad input, and result presentation.

8. **Reporting layer**
   Report generation is a visible subsystem in the frontend: `pdf-report-generator.tsx` and `colorblindness-pdf-generator.tsx` suggest client-side PDF creation for both workflows. These reports are part of the product boundary, not just a UI convenience, because the README describes them as medical-style summaries with treatment/management information.

9. **Alternative UI and training path**
   `app_streamlit.py` provides a second interface focused on retina analysis, likely for quick local experimentation or demoing. `train_ishihara_model.py` is the model-training pipeline for the Ishihara classifier, which makes the repo not just an app but also a small ML development workspace. The actual `.keras` model artifacts are external and intentionally excluded from version control.

10. **Deployment and runtime topology**
   The repository includes deployment assets for a hosted Linux environment: `deployment/nginx/oculusai.conf`, `deployment/systemd/oculusai.service`, and EC2 setup scripts. That implies a production path where Flask is run as a managed service behind **nginx**. `amplify.yml` suggests the frontend may also have a cloud build/deploy path separate from the backend.

11. **Configuration and operational boundary**
   The system is designed for cross-device access on the same network: Flask listens on `0.0.0.0:5000`, and the frontend reads the API base URL from environment config. This is why the architecture diagram should show an explicit network boundary between browser clients and the backend API, with the frontend optionally deployed separately from the Python service.

12. **Important repo-wide constraint**
   The project depends on external model files that are not checked in, so the real inference capability lives in runtime assets outside Git. That makes the architecture dependent on **data/model artifacts** as first-class inputs, alongside code, which is important to represent in any diagram.

Main entry points: [`frontend/app`](https://github.com/adityacodes-root/oculusai/tree/main/frontend/app) (Next.js app), [`flask_app.py`](https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py) (Flask API), [`frontend/app/analyze/page.tsx`](https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/analyze/page.tsx) (Analyze), [`frontend/app/colorblindness/page.tsx`](https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/colorblindness/page.tsx) (Color blindness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_next_app["Next.js app<br/>web app"]
  node_home_page["Home<br/>page<br/>[page.tsx]"]
  node_analyze_page["Analyze<br/>page<br/>[page.tsx]"]
  node_cb_page["Color blindness<br/>page<br/>[page.tsx]"]
  node_disease_page["Diseases<br/>page<br/>[page.tsx]"]
  node_eval_page["Evaluation<br/>page<br/>[page.tsx]"]
  node_reporting_ui["Reports<br/>ui"]
  node_cb_report_ui["CB report<br/>ui"]
  node_ui_shell["UI shell<br/>components<br/>[header.tsx]"]
end

subgraph group_backend["Backend & ML"]
  node_api_server["Flask API<br/>python server<br/>[flask_app.py]"]
  node_retina_model{{"Retina classifier<br/>ML inference<br/>[flask_app.py]"}}
  node_cb_model{{"Ishihara model<br/>ML inference<br/>[flask_app.py]"}}
  node_validator["Image validator<br/>preprocess<br/>[flask_app.py]"]
  node_streamlit_app["Streamlit app<br/>alt UI<br/>[app_streamlit.py]"]
  node_train_pipeline["Training script"]
end

subgraph group_ops["Deployment & Runtime"]
  node_env_config["API config<br/>[.env.local]"]
  node_nginx_conf["Nginx config<br/>deploy config<br/>[oculusai.conf]"]
  node_systemd_unit["Service unit<br/>deploy config<br/>[oculusai.service]"]
  node_deploy_scripts["Setup scripts<br/>ops scripts<br/>[setup-services.sh]"]
end

subgraph group_data["Data & Artifacts"]
  node_sample_retina[("Retinal samples<br/>image data")]
  node_cb_plates[("Ishihara plates<br/>image data")]
end

node_browser(("User client<br/>browser"))

node_browser -->|"uses"| node_next_app
node_next_app -->|"routes"| node_home_page
node_next_app -->|"routes"| node_analyze_page
node_next_app -->|"routes"| node_cb_page
node_next_app -->|"routes"| node_disease_page
node_next_app -->|"routes"| node_eval_page
node_next_app -->|"composes"| node_ui_shell
node_analyze_page -->|"renders"| node_reporting_ui
node_cb_page -->|"renders"| node_cb_report_ui
node_next_app -->|"configures"| node_env_config
node_analyze_page -->|"calls"| node_api_server
node_cb_page -->|"calls"| node_api_server
node_api_server -->|"validates"| node_validator
node_api_server -->|"predicts"| node_retina_model
node_api_server -->|"predicts"| node_cb_model
node_analyze_page -->|"loads"| node_sample_retina
node_cb_page -->|"loads"| node_cb_plates
node_streamlit_app -->|"uses"| node_retina_model
node_train_pipeline -->|"trains on"| node_cb_plates
node_nginx_conf -->|"proxies"| node_api_server
node_systemd_unit -->|"manages"| node_api_server
node_deploy_scripts -->|"installs"| node_systemd_unit
node_deploy_scripts -->|"deploys"| node_nginx_conf

click node_next_app "https://github.com/adityacodes-root/oculusai/tree/main/frontend/app"
click node_home_page "https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/page.tsx"
click node_analyze_page "https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/analyze/page.tsx"
click node_cb_page "https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/colorblindness/page.tsx"
click node_disease_page "https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/diseases/page.tsx"
click node_eval_page "https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/evaluation/page.tsx"
click node_reporting_ui "https://github.com/adityacodes-root/oculusai/blob/main/frontend/components/pdf-report-generator.tsx"
click node_cb_report_ui "https://github.com/adityacodes-root/oculusai/blob/main/frontend/components/colorblindness-pdf-generator.tsx"
click node_ui_shell "https://github.com/adityacodes-root/oculusai/blob/main/frontend/components/header.tsx"
click node_api_server "https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py"
click node_retina_model "https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py"
click node_cb_model "https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py"
click node_validator "https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py"
click node_streamlit_app "https://github.com/adityacodes-root/oculusai/blob/main/app_streamlit.py"
click node_train_pipeline "https://github.com/adityacodes-root/oculusai/blob/main/train_ishihara_model.py"
click node_sample_retina "https://github.com/adityacodes-root/oculusai/tree/main/Sample_Retinal_Images"
click node_cb_plates "https://github.com/adityacodes-root/oculusai/tree/main/CBTestImages"
click node_env_config "https://github.com/adityacodes-root/oculusai/blob/main/frontend/.env.local"
click node_nginx_conf "https://github.com/adityacodes-root/oculusai/blob/main/deployment/nginx/oculusai.conf"
click node_systemd_unit "https://github.com/adityacodes-root/oculusai/blob/main/deployment/systemd/oculusai.service"
click node_deploy_scripts "https://github.com/adityacodes-root/oculusai/blob/main/deployment/scripts/setup-services.sh"

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_next_app,node_home_page,node_analyze_page,node_cb_page,node_disease_page,node_eval_page,node_reporting_ui,node_cb_report_ui,node_ui_shell toneBlue
class node_api_server,node_retina_model,node_cb_model,node_validator,node_streamlit_app,node_train_pipeline toneAmber
class node_env_config,node_nginx_conf,node_systemd_unit,node_deploy_scripts toneMint
class node_sample_retina,node_cb_plates toneRose
class node_browser toneNeutral
```

## Components

### Frontend

Next.js app for user interaction, results, and report generation

- [Next.js app](https://github.com/adityacodes-root/oculusai/tree/main/frontend/app): web app · Main React frontend and route shell · `frontend/app`
- [Home](https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/page.tsx): page · Landing page and entry flow · `frontend/app/page.tsx`
- [Analyze](https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/analyze/page.tsx): page · Image upload and retinal analysis UI · `frontend/app/analyze/page.tsx`
- [Color blindness](https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/colorblindness/page.tsx): page · Ishihara test flow and diagnosis UI · `frontend/app/colorblindness/page.tsx`
- [Diseases](https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/diseases/page.tsx): page · Disease information and results entry point · `frontend/app/diseases/page.tsx`
- [Evaluation](https://github.com/adityacodes-root/oculusai/blob/main/frontend/app/evaluation/page.tsx): page · Assessment and evaluation UI · `frontend/app/evaluation/page.tsx`
- [Reports](https://github.com/adityacodes-root/oculusai/blob/main/frontend/components/pdf-report-generator.tsx): ui · Client-side PDF report generation for both workflows · `frontend/components/pdf-report-generator.tsx`
- [CB report](https://github.com/adityacodes-root/oculusai/blob/main/frontend/components/colorblindness-pdf-generator.tsx): ui · Color blindness PDF report composition · `frontend/components/colorblindness-pdf-generator.tsx`
- [UI shell](https://github.com/adityacodes-root/oculusai/blob/main/frontend/components/header.tsx): components · Shared layout, navigation, theme, and reusable primitives · `frontend/components/header.tsx`

### Backend & ML

Python services and model workflows for inference and validation

- [Flask API](https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py): python server · Main inference service for validation and diagnosis · `flask_app.py`
- [Retina classifier](https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py): ML inference · Predicts cataract, diabetic retinopathy, glaucoma, or normal · `flask_app.py`
- [Ishihara model](https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py): ML inference · Recognizes Ishihara digits and color deficiency type · `flask_app.py`
- [Image validator](https://github.com/adityacodes-root/oculusai/blob/main/flask_app.py): preprocess · Checks whether uploaded input is a valid fundus image · `flask_app.py`
- [Streamlit app](https://github.com/adityacodes-root/oculusai/blob/main/app_streamlit.py): alt UI · Alternate retina-analysis interface for local use · `app_streamlit.py`
- [Training script](https://github.com/adityacodes-root/oculusai/blob/main/train_ishihara_model.py): training · Builds the Ishihara classifier from data/model artifacts · `train_ishihara_model.py`

### Deployment & Runtime

Hosting, service, and model-deployment assets

- [API config](https://github.com/adityacodes-root/oculusai/blob/main/frontend/.env.local): config · Frontend environment variable for backend endpoint · `frontend/.env.local`
- [Nginx config](https://github.com/adityacodes-root/oculusai/blob/main/deployment/nginx/oculusai.conf): deploy config · Reverse proxy and production web serving setup · `deployment/nginx/oculusai.conf`
- [Service unit](https://github.com/adityacodes-root/oculusai/blob/main/deployment/systemd/oculusai.service): deploy config · Managed backend service definition on Linux hosts · `deployment/systemd/oculusai.service`
- [Setup scripts](https://github.com/adityacodes-root/oculusai/blob/main/deployment/scripts/setup-services.sh): ops scripts · Host bootstrap and model upload helpers · `deployment/scripts/setup-services.sh`

### Data & Artifacts

Sample images and external model inputs used by the application

- [Retinal samples](https://github.com/adityacodes-root/oculusai/tree/main/Sample_Retinal_Images): image data · Sample fundus images used for demos and testing · `Sample_Retinal_Images`
- [Ishihara plates](https://github.com/adityacodes-root/oculusai/tree/main/CBTestImages): image data · Color blindness test images used by the frontend · `CBTestImages`

### Other components

- **User client**: browser · End-user access point for uploads, tests, and reports

## Connections

- User client → Next.js app: uses · Users interact with the frontend in the browser
- Next.js app → Home: routes · Homepage route
- Next.js app → Analyze: routes · Retinal analysis route
- Next.js app → Color blindness: routes · Color blindness route
- Next.js app → Diseases: routes · Disease information route
- Next.js app → Evaluation: routes · Evaluation route
- Next.js app → UI shell: composes · Shared navigation and styling layer
- Analyze → Reports: renders · Generates retinal PDF summaries
- Color blindness → CB report: renders · Generates color blindness PDF summaries
- Next.js app → API config: configures · Frontend reads backend API base URL
- Analyze → Flask API: calls · Sends retinal images for validation and prediction
- Color blindness → Flask API: calls · Sends Ishihara results or images for diagnosis
- Flask API → Image validator: validates · Ensures uploaded images are suitable for inference
- Flask API → Retina classifier: predicts · Runs retinal disease classification
- Flask API → Ishihara model: predicts · Runs color vision / Ishihara inference
- Analyze → Retinal samples: loads · Uses sample retinal images in the UI
- Color blindness → Ishihara plates: loads · Uses Ishihara test plates in the UI
- Streamlit app → Retina classifier: uses · Alternate interface for retinal analysis
- Training script → Ishihara plates: trains on · Training data for Ishihara classifier
- Nginx config → Flask API: proxies · Production reverse proxy for Flask service
- Service unit → Flask API: manages · Runs Flask as a managed service
- Setup scripts → Service unit: installs · Automates service setup on hosts
- Setup scripts → Nginx config: deploys · Places production nginx config
