# satvikkaul/secure-pathology-dashboard architecture

> Architecture diagram of the GitHub repository satvikkaul/secure-pathology-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satvikkaul/secure-pathology-dashboard
- Repository: https://github.com/satvikkaul/secure-pathology-dashboard

## Overview

1. **Overall shape**
   This is a two-tier local prototype: a React/Vite frontend talks to a FastAPI backend over `/api/*`, and the backend persists data in a local SQLite database plus a private upload directory. There is no queue, cloud service, or background worker in Phase 1.

2. **Frontend application**
   The frontend is a single-page app built with React 19 and React Router. Its main runtime pieces are:
   - `AuthContext` for token/user state
   - `ProtectedRoute` for route gating
   - `AppLayout` for the shared dashboard shell/sidebar
   - page modules for Login, Register, Dashboard, Upload, Jobs, and Job Result
   The frontend stores the JWT in `localStorage`, so session state is client-managed and cleared on auth failures or logout.

3. **Frontend-to-backend integration**
   All API calls are centralized under `frontend/src/api/*` with a shared client wrapper. Vite is configured as a dev proxy so browser requests to `/api` are forwarded to `localhost:8000`. This keeps the browser origin simple while the backend remains a separate service.

4. **Authentication boundary**
   Authentication is handled by `backend/app/auth.py` and `backend/app/routers/auth.py`. Users register and log in with email/password, passwords are hashed with bcrypt, and the backend issues JWTs. `dependencies.py` enforces authentication on protected endpoints by decoding the token and loading the current user.

5. **User data isolation**
   A core architectural rule is per-user isolation at the API layer. Images and jobs are always queried through the authenticated user context, so a user can list only their own records and gets a 404 when trying to access another user’s image/job IDs. This is a backend enforcement boundary, not just a frontend UI restriction.

6. **Image upload subsystem**
   Uploads are handled by `backend/app/routers/images.py` and stored under `backend/uploads/`, which is intentionally outside the web root. The backend validates file type, file size, and image bytes using Pillow before accepting the upload. The accepted formats are JPG and PNG, with a 10 MB limit.

7. **Algorithm registry and selection**
   `backend/app/models.py` includes an `Algorithm` entity, and the app startup logic seeds a placeholder algorithm (`placeholder_v1`). The algorithms router exposes the available algorithms to the frontend so the upload flow can select one before job submission.

8. **Job submission and result flow**
   The jobs router creates an analysis job from an uploaded image plus selected algorithm. In Phase 1, execution is synchronous: the placeholder algorithm runs immediately and writes a synthetic result directly onto the job record. The frontend then navigates to a result page that reads the completed job and displays the report fields.

9. **Persistence model**
   SQLite is the only database, managed through SQLAlchemy in `backend/app/database.py`. The main ORM entities are User, Image, Algorithm, and AlgorithmJob. `backend/app/main.py` initializes the schema on startup, so the system self-boots without manual migration or database provisioning.

10. **Backend modularity**
    The backend is organized into small FastAPI routers:
   - `auth.py` for registration/login/current-user
   - `images.py` for upload and image retrieval
   - `algorithms.py` for algorithm listing
   - `jobs.py` for job create/list/detail
   Shared schema definitions live in `schemas.py`, and dependency wiring is separated into `dependencies.py`. This makes the runtime boundaries clean: routers handle HTTP, models handle persistence, and algorithms are isolated in their own package.

11. **Non-runtime materials**
    The `docs/` folder, mockups, and Claude skill files are supporting materials for planning and workflow, not part of the application runtime. The frontend mockups are static references, and the docs describe assumptions, decisions, and next steps for future phases.

12. **Important architecture constraints**
    Phase 1 is intentionally local and synthetic: no real patient data, no real model inference, no async job queue, no Dockerized algorithm execution, and no production security model like `httpOnly` cookies. For a diagram, the critical path is: browser UI → FastAPI auth/upload/job APIs → SQLite + upload storage → synchronous placeholder analysis → result display.

Main entry points: [`backend/app/main.py`](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/models.py`](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/models.py) (ORM Models), [`frontend/src/api/client.js`](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/client.js) (API Client), [`backend/app/routers/images.py`](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/images.py) (Images Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser["Browser UI<br/>spa shell<br/>[App.jsx]"]
  node_auth_context(("Auth State<br/>react context<br/>[AuthContext.jsx]"))
  node_route_gate{{"Route Gate<br/>route guard<br/>[ProtectedRoute.jsx]"}}
  node_shell["Dashboard Shell<br/>layout<br/>[AppLayout.jsx]"]
  node_frontend_api["API Client<br/>api wrapper<br/>[client.js]"]
  node_api_auth["Auth API<br/>frontend api<br/>[auth.js]"]
  node_api_images["Image API<br/>frontend api<br/>[images.js]"]
  node_api_algorithms["Algo API<br/>frontend api<br/>[algorithms.js]"]
  node_api_jobs["Jobs API<br/>frontend api<br/>[jobs.js]"]
end

subgraph group_backend["Backend"]
  node_fastapi_app["FastAPI App<br/>service entry<br/>[main.py]"]
  node_auth_router["Auth Router<br/>http router<br/>[auth.py]"]
  node_image_router["Images Router<br/>http router<br/>[images.py]"]
  node_algo_router["Algorithms Router<br/>http router<br/>[algorithms.py]"]
  node_jobs_router["Jobs Router<br/>http router<br/>[jobs.py]"]
  node_auth_core{{"Auth Core<br/>jwt+bcrypt<br/>[auth.py]"}}
  node_deps{{"Dependencies<br/>auth guard<br/>[dependencies.py]"}}
  node_models[("ORM Models<br/>sqlalchemy models<br/>[models.py]")]
  node_schemas["Schemas<br/>[schemas.py]"]
  node_database[("SQLite DB<br/>[database.py]")]
  node_uploads["Upload Store<br/>file storage<br/>[.gitkeep]"]
  node_placeholder{{"Placeholder Algo<br/>analysis routine<br/>[placeholder.py]"}}
end

subgraph group_support["Support"]
  node_mockups["Mockups<br/>design refs<br/>[login.html]"]
  node_docs["Docs<br/>[DECISIONS.md]"]
end

node_browser -->|"session state"| node_auth_context
node_browser -->|"gated routes"| node_route_gate
node_route_gate -->|"renders"| node_shell
node_browser -->|"requests"| node_frontend_api
node_frontend_api -->|"auth calls"| node_api_auth
node_frontend_api -->|"image calls"| node_api_images
node_frontend_api -->|"algo calls"| node_api_algorithms
node_frontend_api -->|"job calls"| node_api_jobs
node_frontend_api -->|"/api proxy"| node_fastapi_app
node_fastapi_app -->|"mounts"| node_auth_router
node_fastapi_app -->|"mounts"| node_image_router
node_fastapi_app -->|"mounts"| node_algo_router
node_fastapi_app -->|"mounts"| node_jobs_router
node_auth_router -->|"uses"| node_auth_core
node_auth_router -->|"guards"| node_deps
node_image_router -->|"guards"| node_deps
node_jobs_router -->|"guards"| node_deps
node_auth_core -->|"loads users"| node_models
node_deps -->|"loads current user"| node_models
node_models -->|"persists"| node_database
node_image_router -->|"stores files"| node_uploads
node_image_router -->|"creates images"| node_models
node_algo_router -->|"lists algorithms"| node_models
node_jobs_router -->|"runs analysis"| node_placeholder
node_placeholder -->|"writes result"| node_models
node_fastapi_app -->|"validates payloads"| node_schemas
node_fastapi_app -->|"initializes schema"| node_models
node_docs -.->|"supports"| node_mockups

click node_browser "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/context/AuthContext.jsx"
click node_route_gate "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_shell "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/components/AppLayout.jsx"
click node_frontend_api "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/client.js"
click node_api_auth "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/auth.js"
click node_api_images "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/images.js"
click node_api_algorithms "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/algorithms.js"
click node_api_jobs "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/jobs.js"
click node_fastapi_app "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/main.py"
click node_auth_router "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/auth.py"
click node_image_router "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/images.py"
click node_algo_router "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/algorithms.py"
click node_jobs_router "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/jobs.py"
click node_auth_core "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/auth.py"
click node_deps "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/dependencies.py"
click node_models "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/models.py"
click node_schemas "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/schemas.py"
click node_database "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/database.py"
click node_uploads "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/uploads/.gitkeep"
click node_placeholder "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/algorithms/placeholder.py"
click node_mockups "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/mockups/login.html"
click node_docs "https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/docs/DECISIONS.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_browser,node_auth_context,node_route_gate,node_shell,node_frontend_api,node_api_auth,node_api_images,node_api_algorithms,node_api_jobs toneBlue
class node_fastapi_app,node_auth_router,node_image_router,node_algo_router,node_jobs_router,node_auth_core,node_deps,node_models,node_schemas,node_database,node_uploads,node_placeholder toneAmber
class node_mockups,node_docs toneMint
```

## Components

### Frontend

React/Vite single-page app and browser-side API integration.

- [Browser UI](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/App.jsx): spa shell · Single-page React app for auth, upload, jobs, and results. · `frontend/src/App.jsx`
- [Auth State](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/context/AuthContext.jsx): react context · Stores JWT/user state in localStorage and drives session handling. · `frontend/src/context/AuthContext.jsx`
- [Route Gate](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/components/ProtectedRoute.jsx): route guard · Protects authenticated pages from unauthenticated access. · `frontend/src/components/ProtectedRoute.jsx`
- [Dashboard Shell](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/components/AppLayout.jsx): layout · Shared authenticated layout and navigation chrome. · `frontend/src/components/AppLayout.jsx`
- [API Client](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/client.js): api wrapper · Central frontend client used by feature-specific API modules. · `frontend/src/api/client.js`
- [Auth API](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/auth.js): frontend api · Login, register, and current-user requests. · `frontend/src/api/auth.js`
- [Image API](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/images.js): frontend api · Upload and image retrieval requests. · `frontend/src/api/images.js`
- [Algo API](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/algorithms.js): frontend api · Fetches available algorithms for upload selection. · `frontend/src/api/algorithms.js`
- [Jobs API](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/src/api/jobs.js): frontend api · Creates jobs and reads job lists and details. · `frontend/src/api/jobs.js`

### Backend

FastAPI service, persistence, auth, and local analysis flow.

- [FastAPI App](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/main.py): service entry · Backend application startup, routing, and schema initialization. · `backend/app/main.py`
- [Auth Router](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/auth.py): http router · Registration, login, and current-user endpoints. · `backend/app/routers/auth.py`
- [Images Router](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/images.py): http router · Upload and authenticated image retrieval endpoints. · `backend/app/routers/images.py`
- [Algorithms Router](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/algorithms.py): http router · Exposes available algorithms to the client. · `backend/app/routers/algorithms.py`
- [Jobs Router](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/routers/jobs.py): http router · Creates jobs and serves job lists, detail, and result data. · `backend/app/routers/jobs.py`
- [Auth Core](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/auth.py): jwt+bcrypt · Password hashing, token issuance, and token decoding. · `backend/app/auth.py`
- [Dependencies](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/dependencies.py): auth guard · Loads the current user and enforces protected backend access. · `backend/app/dependencies.py`
- [ORM Models](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/models.py): sqlalchemy models · User, Image, Algorithm, and AlgorithmJob entities. · `backend/app/models.py`
- [Schemas](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/schemas.py): pydantic schemas · Shared request and response shapes for the API. · `backend/app/schemas.py`
- [SQLite DB](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/database.py): sqlite · Local database managed through SQLAlchemy. · `backend/app/database.py`
- [Upload Store](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/uploads/.gitkeep): file storage · Private local directory for accepted image files. · `backend/uploads/.gitkeep`
- [Placeholder Algo](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/backend/app/algorithms/placeholder.py): analysis routine · Synchronous synthetic analysis used in Phase 1. · `backend/app/algorithms/placeholder.py`

### Support

Docs, mockups, and planning materials outside the runtime.

- [Mockups](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/frontend/mockups/login.html): design refs · Static UI references for pages and flows. · `frontend/mockups/login.html`
- [Docs](https://github.com/satvikkaul/secure-pathology-dashboard/blob/main/docs/DECISIONS.md): planning docs · Assumptions, decisions, context, and next-step notes. · `docs/DECISIONS.md`

## Connections

- Browser UI → Auth State: session state · The UI reads and updates login state.
- Browser UI → Route Gate: gated routes · Authenticated pages are wrapped by the route guard.
- Route Gate → Dashboard Shell: renders · Protected areas open inside the shared dashboard shell.
- Browser UI → API Client: requests · Pages call the shared API client for backend access.
- API Client → Auth API: auth calls · Feature module for authentication flows.
- API Client → Image API: image calls · Feature module for uploads and image access.
- API Client → Algo API: algo calls · Feature module for algorithm listing.
- API Client → Jobs API: job calls · Feature module for job creation and reads.
- API Client → FastAPI App: /api proxy · Vite forwards browser API traffic to the backend service.
- FastAPI App → Auth Router: mounts · Backend exposes auth endpoints through a router.
- FastAPI App → Images Router: mounts · Backend exposes image endpoints through a router.
- FastAPI App → Algorithms Router: mounts · Backend exposes algorithm listing through a router.
- FastAPI App → Jobs Router: mounts · Backend exposes job endpoints through a router.
- Auth Router → Auth Core: uses · Router delegates password and token handling to auth core.
- Auth Router → Dependencies: guards · Protected auth-related reads depend on current-user resolution.
- Images Router → Dependencies: guards · Image access is scoped to the authenticated user.
- Jobs Router → Dependencies: guards · Job access is scoped to the authenticated user.
- Auth Core → ORM Models: loads users · Auth logic works against ORM user records.
- Dependencies → ORM Models: loads current user · Dependency layer resolves user context from the token.
- ORM Models → SQLite DB: persists · ORM entities are stored in SQLite.
- Images Router → Upload Store: stores files · Accepted image bytes are written to the private upload directory.
- Images Router → ORM Models: creates images · Image metadata is recorded per authenticated user.
- Algorithms Router → ORM Models: lists algorithms · Algorithm entities are read from persistence.
- Jobs Router → Placeholder Algo: runs analysis · Job creation triggers synchronous placeholder execution.
- Placeholder Algo → ORM Models: writes result · Synthetic output is stored on the job record.
- FastAPI App → Schemas: validates payloads · Routers share request and response schemas.
- FastAPI App → ORM Models: initializes schema · Startup creates the database schema on boot.
- Docs → Mockups: supports · Planning and design references describe the intended flows.
