How adityacodes-root/oculusai works
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: app Next.js app · flask_app.py Flask API · analyze/page.tsx Analyze · colorblindness/page.tsx Color blindness
Components 22
Frontend
Next.js app for user interaction, results, and report generation
- Next.js app · Main React frontend and route shell
frontend/app - Home · Landing page and entry flow
frontend/app/page.tsx - Analyze · Image upload and retinal analysis UI
frontend/app/analyze/page.tsx - Color blindness · Ishihara test flow and diagnosis UI
frontend/app/colorblindness/page.tsx - Diseases · Disease information and results entry point
frontend/app/diseases/page.tsx - Evaluation · Assessment and evaluation UI
frontend/app/evaluation/page.tsx - Reports · Client-side PDF report generation for both workflows
frontend/components/pdf-report-generator.tsx - CB report · Color blindness PDF report composition
frontend/components/colorblindness-pdf-generator.tsx - UI shell · Shared layout, navigation, theme, and reusable primitives
frontend/components/header.tsx
Backend & ML
Python services and model workflows for inference and validation
- Flask API · Main inference service for validation and diagnosis
flask_app.py - Retina classifier · Predicts cataract, diabetic retinopathy, glaucoma, or normal
flask_app.py - Ishihara model · Recognizes Ishihara digits and color deficiency type
flask_app.py - Image validator · Checks whether uploaded input is a valid fundus image
flask_app.py - Streamlit app · Alternate retina-analysis interface for local use
app_streamlit.py - Training script · Builds the Ishihara classifier from data/model artifacts
train_ishihara_model.py
Deployment & Runtime
Hosting, service, and model-deployment assets
- API config · Frontend environment variable for backend endpoint
frontend/.env.local - Nginx config · Reverse proxy and production web serving setup
deployment/nginx/oculusai.conf - Service unit · Managed backend service definition on Linux hosts
deployment/systemd/oculusai.service - Setup 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 · Sample fundus images used for demos and testing
Sample_Retinal_Images - Ishihara plates · Color blindness test images used by the frontend
CBTestImages
Other components
- User client · End-user access point for uploads, tests, and reports
Connections 23
- 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