How satvikkaul/secure-pathology-dashboard works
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: main.py FastAPI App · models.py ORM Models · client.js API Client · images.py Images Router
Components 23
Frontend
React/Vite single-page app and browser-side API integration.
- Browser UI · Single-page React app for auth, upload, jobs, and results.
frontend/src/App.jsx - Auth State · Stores JWT/user state in localStorage and drives session handling.
frontend/src/context/AuthContext.jsx - Route Gate · Protects authenticated pages from unauthenticated access.
frontend/src/components/ProtectedRoute.jsx - Dashboard Shell · Shared authenticated layout and navigation chrome.
frontend/src/components/AppLayout.jsx - API Client · Central frontend client used by feature-specific API modules.
frontend/src/api/client.js - Auth API · Login, register, and current-user requests.
frontend/src/api/auth.js - Image API · Upload and image retrieval requests.
frontend/src/api/images.js - Algo API · Fetches available algorithms for upload selection.
frontend/src/api/algorithms.js - Jobs 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 · Backend application startup, routing, and schema initialization.
backend/app/main.py - Auth Router · Registration, login, and current-user endpoints.
backend/app/routers/auth.py - Images Router · Upload and authenticated image retrieval endpoints.
backend/app/routers/images.py - Algorithms Router · Exposes available algorithms to the client.
backend/app/routers/algorithms.py - Jobs Router · Creates jobs and serves job lists, detail, and result data.
backend/app/routers/jobs.py - Auth Core · Password hashing, token issuance, and token decoding.
backend/app/auth.py - Dependencies · Loads the current user and enforces protected backend access.
backend/app/dependencies.py - ORM Models · User, Image, Algorithm, and AlgorithmJob entities.
backend/app/models.py - Schemas · Shared request and response shapes for the API.
backend/app/schemas.py - SQLite DB · Local database managed through SQLAlchemy.
backend/app/database.py - Upload Store · Private local directory for accepted image files.
backend/uploads/.gitkeep - Placeholder Algo · Synchronous synthetic analysis used in Phase 1.
backend/app/algorithms/placeholder.py
Connections 28
- 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.