How suprxyyaa/share_ works
1. This repo is a two-tier healthcare platform: a Next.js 14 frontend and a FastAPI backend. The frontend handles role-based user journeys, while the backend owns authentication, business rules, file access control, and persistence.
2. The backend is organized as a classic API + service + data layer. app/api/* contains route handlers, app/services/* contains domain logic, app/models/tables.py defines the PostgreSQL schema, and app/db.py / app/dependencies.py wire database access and request dependencies into the API.
3. The main backend domains are split by concern: auth, doctors, appointments, files, and admin. Each API module maps to a service module, which keeps controllers thin and centralizes workflows like doctor approval, appointment lifecycle, and file sharing.
4. PostgreSQL on Neon is the system of record. The schema includes user and role profiles, doctor availability, appointments, medical files, file permissions, audit logs, and reviews. This means most platform state is persistent and relational rather than event-based or document-based.
5. Cloudinary is used as the external file store for sensitive uploads. Medical records and doctor certificates are uploaded to Cloudinary, while the backend stores metadata and access control state in PostgreSQL. The architecture therefore separates binary storage from authorization metadata.
6. The file-sharing subsystem is the most security-sensitive boundary in the system. A single authorize() service is the only place that decides whether a doctor may access a patient file. Access depends on an explicit permission, expiry, and revocation state, and every attempt is written to audit_log.
7. Authentication is JWT-based. Users register and log in through backend auth endpoints, and the frontend keeps the session client-side using its lib/auth.ts and lib/axios.ts helpers. The backend also defines an admin identity via configured credentials for platform moderation.
8. The frontend uses the Next.js App Router with route groups that map directly to user roles: (auth), (patient), (doctor), and (admin). This makes the UI architecture role-centric: login/register flows are separate from patient dashboards, doctor availability management, and admin verification screens.
9. Core user flows are implemented end-to-end across both layers:
- Patients search verified doctors, book appointments, upload records, share files, and revoke access.
- Doctors register with a certificate, wait for approval, manage availability, and confirm or cancel appointments.
- Admins review pending doctor verifications, inspect certificates, and approve or reject accounts.
10. Appointments are a separate workflow from file sharing. Patients book doctors via the appointments API, doctors later confirm or cancel, and video visits are supported by generating a Jitsi meeting link automatically. This keeps scheduling state independent from medical-record access state.
11. start.sh is the operational entry point that launches both services together for local development. The backend runs at 127.0.0.1:8000 and exposes Swagger docs, while the frontend runs at localhost:3000.
12. The main architectural boundaries to show in a diagram are: browser/frontend, backend API layer, backend business services, PostgreSQL, Cloudinary, and external Jitsi links. The most important trust boundary is the backend authorization layer, especially around file access and admin moderation.
Main entry points: api API layer · tables.py PostgreSQL schema · app Next.js app · lib Client helpers
Components 27
Frontend
Next.js App Router UI split by user role and session helpers.
- Next.js app · Role-based App Router UI for patients, doctors, admins, and auth flows.
frontend/app - Auth UI · Login and registration screens for client-side session entry.
frontend/app/(auth) - Patient UI · Patient journey for discovery, booking, records, and payments.
frontend/app/(patient) - Doctor UI · Doctor dashboard and availability management screens.
frontend/app/(doctor) - Admin UI · Admin verification and moderation screens.
frontend/app/(admin) - Client helpers · Browser-side auth and API client helpers used across the UI.
frontend/lib
Backend
FastAPI API, services, and PostgreSQL-backed persistence.
- FastAPI app · Backend application entrypoint and HTTP surface.
backend/app - API layer · Thin FastAPI route modules for each domain boundary.
backend/app/api - Auth API · Register, login, and JWT-facing authentication endpoints.
backend/app/api/auth.py - Doctors API · Doctor registration, profile, approval, and availability endpoints.
backend/app/api/doctors.py - Appointments API · Booking and lifecycle endpoints for patient-doctor appointments.
backend/app/api/appointments.py - Files API · Upload, share, revoke, and access-check endpoints for medical files.
backend/app/api/files.py - Admin API · Moderation endpoints for doctor verification and platform review.
backend/app/api/admin.py - Service layer · Domain workflows that centralize rules and coordinate persistence.
backend/app/services - Auth service · User identity, registration, login, and credential workflows.
backend/app/services/auth_service.py - Doctor service · Doctor onboarding, verification, and availability workflows.
backend/app/services/doctor_service.py - Appointment service · Appointment booking, confirmation, cancellation, and meeting-link creation.
backend/app/services/appointment_service.py - File service · Cloudinary-backed upload and metadata coordination for medical files.
backend/app/services/file_service.py - Authorize · Single security boundary for file access decisions, expiries, revocation, and auditing.
backend/app/services/authorize.py - Admin service · Doctor review and administrative approval/rejection workflows.
backend/app/services/admin_service.py - PostgreSQL schema · System of record for users, roles, doctors, appointments, files, permissions, audits, and reviews.
backend/app/models/tables.py - DB wiring · Database engine/session wiring and request dependencies for the API.
backend/app/db.py - Dependencies · FastAPI dependency wiring for auth, database, and request-scoped services.
backend/app/dependencies.py
External systems
Third-party services and operational entrypoints.
- Cloudinary · Binary storage for uploaded medical records and doctor certificates.
- Neon Postgres · Hosted PostgreSQL backing persistent platform state.
- Jitsi links · Generated video visit links for scheduled appointments.
- Start script · Development script that launches frontend and backend together.
start.sh
Connections 33
- Next.js app → Auth UI: routes to · App Router groups the auth journey separately from logged-in areas.
- Next.js app → Patient UI: routes to · Patient-facing dashboard and task flows.
- Next.js app → Doctor UI: routes to · Doctor-facing dashboard and availability flows.
- Next.js app → Admin UI: routes to · Admin moderation screens.
- Patient UI → Client helpers: uses · Patient screens call the client helpers for auth and API requests.
- Doctor UI → Client helpers: uses · Doctor screens reuse the same session and HTTP helpers.
- Admin UI → Client helpers: uses · Admin screens use the shared client helpers.
- Auth UI → Client helpers: uses · Login and registration rely on shared client-side auth helpers.
- Client helpers → API layer: calls · Frontend talks to the backend through HTTP endpoints.
- FastAPI app → API layer: exposes · FastAPI application mounts the domain route modules.
- API layer → Auth API: includes · Authentication routes.
- API layer → Doctors API: includes · Doctor routes.
- API layer → Appointments API: includes · Appointment routes.
- API layer → Files API: includes · File-sharing routes.
- API layer → Admin API: includes · Admin routes.
- Auth API → Auth service: delegates to · Auth handlers keep business logic in the service layer.
- Doctors API → Doctor service: delegates to · Doctor handlers delegate workflow logic.
- Appointments API → Appointment service: delegates to · Scheduling handlers delegate workflow logic.
- Files API → File service: delegates to · File handlers delegate upload and sharing logic.
- Files API → Authorize: checks access · All sensitive file access is decided by the authorize boundary.
- Admin API → Admin service: delegates to · Admin moderation handlers delegate workflow logic.
- Auth service → PostgreSQL schema: reads/writes · User accounts and roles are persisted in PostgreSQL.
- Doctor service → PostgreSQL schema: reads/writes · Doctor profiles, certificates, and availability are persisted.
- Appointment service → PostgreSQL schema: reads/writes · Appointment state is stored relationally.
- File service → PostgreSQL schema: reads/writes · File metadata and permissions are stored in PostgreSQL.
- Authorize → PostgreSQL schema: reads/writes · Permission checks inspect and record access state and audits.
- Admin service → PostgreSQL schema: reads/writes · Verification and moderation state are persisted.
- DB wiring → Neon Postgres: connects to · Database wiring targets Neon-hosted PostgreSQL.
- Dependencies → DB wiring: uses · Request dependencies obtain DB access through shared wiring.
- File service → Cloudinary: stores blobs · Uploads and certificates are stored externally as binary objects.
- Appointment service → Jitsi links: generates links · Video visit links are created for confirmed appointments.
- Start script → Next.js app: starts · Development script launches the frontend service.
- Start script → FastAPI app: starts · Development script launches the backend service.