# suprxyyaa/share_ architecture

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

- Interactive diagram: https://gitdiagram.com/suprxyyaa/share_
- Repository: https://github.com/suprxyyaa/share_

## Overview

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: [`backend/app/api`](https://github.com/suprxyyaa/share_/tree/main/backend/app/api) (API layer), [`backend/app/models/tables.py`](https://github.com/suprxyyaa/share_/blob/main/backend/app/models/tables.py) (PostgreSQL schema), [`frontend/app`](https://github.com/suprxyyaa/share_/tree/main/frontend/app) (Next.js app), [`frontend/lib`](https://github.com/suprxyyaa/share_/tree/main/frontend/lib) (Client helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js app<br/>web frontend"]
  node_frontend_auth["Auth UI<br/>route group"]
  node_frontend_patient["Patient UI<br/>route group"]
  node_frontend_doctor["Doctor UI<br/>route group"]
  node_frontend_admin["Admin UI<br/>route group"]
  node_frontend_lib["Client helpers<br/>session/http"]
end

subgraph group_backend["Backend"]
  node_backend_app["FastAPI app<br/>api backend"]
  node_backend_api["API layer<br/>route handlers"]
  node_api_auth["Auth API<br/>routes<br/>[auth.py]"]
  node_api_doctors["Doctors API<br/>routes<br/>[doctors.py]"]
  node_api_appointments["Appointments API<br/>routes<br/>[appointments.py]"]
  node_api_files["Files API<br/>routes<br/>[files.py]"]
  node_api_admin["Admin API<br/>routes<br/>[admin.py]"]
  node_backend_services["Service layer<br/>business logic"]
  node_svc_auth["Auth service<br/>jwt/users<br/>[auth_service.py]"]
  node_svc_doctors["Doctor service<br/>profiles/approval<br/>[doctor_service.py]"]
  node_svc_appointments["Appointment service<br/>scheduling"]
  node_svc_files["File service<br/>storage/access<br/>[file_service.py]"]
  node_svc_authorize{{"Authorize<br/>access control<br/>[authorize.py]"}}
  node_svc_admin["Admin service<br/>moderation<br/>[admin_service.py]"]
  node_backend_data[("PostgreSQL schema<br/>relational model<br/>[tables.py]")]
  node_backend_db["DB wiring<br/>connection layer<br/>[db.py]"]
  node_backend_dep["Dependencies<br/>request context<br/>[dependencies.py]"]
end

subgraph group_external["External systems"]
  node_cloudinary[("Cloudinary<br/>external file store")]
  node_postgres_neon[("Neon Postgres<br/>external database")]
  node_jitsi(("Jitsi links<br/>external meetings"))
  node_start_sh["Start script<br/>local entrypoint<br/>[start.sh]"]
end

node_frontend_app -->|"routes to"| node_frontend_auth
node_frontend_app -->|"routes to"| node_frontend_patient
node_frontend_app -->|"routes to"| node_frontend_doctor
node_frontend_app -->|"routes to"| node_frontend_admin
node_frontend_patient -->|"uses"| node_frontend_lib
node_frontend_doctor -->|"uses"| node_frontend_lib
node_frontend_admin -->|"uses"| node_frontend_lib
node_frontend_auth -->|"uses"| node_frontend_lib
node_frontend_lib -->|"calls"| node_backend_api
node_backend_app -->|"exposes"| node_backend_api
node_backend_api -->|"includes"| node_api_auth
node_backend_api -->|"includes"| node_api_doctors
node_backend_api -->|"includes"| node_api_appointments
node_backend_api -->|"includes"| node_api_files
node_backend_api -->|"includes"| node_api_admin
node_api_auth -->|"delegates to"| node_svc_auth
node_api_doctors -->|"delegates to"| node_svc_doctors
node_api_appointments -->|"delegates to"| node_svc_appointments
node_api_files -->|"delegates to"| node_svc_files
node_api_files -->|"checks access"| node_svc_authorize
node_api_admin -->|"delegates to"| node_svc_admin
node_svc_auth -->|"reads/writes"| node_backend_data
node_svc_doctors -->|"reads/writes"| node_backend_data
node_svc_appointments -->|"reads/writes"| node_backend_data
node_svc_files -->|"reads/writes"| node_backend_data
node_svc_authorize -->|"reads/writes"| node_backend_data
node_svc_admin -->|"reads/writes"| node_backend_data
node_backend_db -->|"connects to"| node_postgres_neon
node_backend_dep -->|"uses"| node_backend_db
node_svc_files -->|"stores blobs"| node_cloudinary
node_svc_appointments -->|"generates links"| node_jitsi
node_start_sh -->|"starts"| node_frontend_app
node_start_sh -->|"starts"| node_backend_app

click node_frontend_app "https://github.com/suprxyyaa/share_/tree/main/frontend/app"
click node_frontend_auth "https://github.com/suprxyyaa/share_/tree/main/frontend/app/(auth)"
click node_frontend_patient "https://github.com/suprxyyaa/share_/tree/main/frontend/app/(patient)"
click node_frontend_doctor "https://github.com/suprxyyaa/share_/tree/main/frontend/app/(doctor)"
click node_frontend_admin "https://github.com/suprxyyaa/share_/tree/main/frontend/app/(admin)"
click node_frontend_lib "https://github.com/suprxyyaa/share_/tree/main/frontend/lib"
click node_backend_app "https://github.com/suprxyyaa/share_/tree/main/backend/app"
click node_backend_api "https://github.com/suprxyyaa/share_/tree/main/backend/app/api"
click node_api_auth "https://github.com/suprxyyaa/share_/blob/main/backend/app/api/auth.py"
click node_api_doctors "https://github.com/suprxyyaa/share_/blob/main/backend/app/api/doctors.py"
click node_api_appointments "https://github.com/suprxyyaa/share_/blob/main/backend/app/api/appointments.py"
click node_api_files "https://github.com/suprxyyaa/share_/blob/main/backend/app/api/files.py"
click node_api_admin "https://github.com/suprxyyaa/share_/blob/main/backend/app/api/admin.py"
click node_backend_services "https://github.com/suprxyyaa/share_/tree/main/backend/app/services"
click node_svc_auth "https://github.com/suprxyyaa/share_/blob/main/backend/app/services/auth_service.py"
click node_svc_doctors "https://github.com/suprxyyaa/share_/blob/main/backend/app/services/doctor_service.py"
click node_svc_appointments "https://github.com/suprxyyaa/share_/blob/main/backend/app/services/appointment_service.py"
click node_svc_files "https://github.com/suprxyyaa/share_/blob/main/backend/app/services/file_service.py"
click node_svc_authorize "https://github.com/suprxyyaa/share_/blob/main/backend/app/services/authorize.py"
click node_svc_admin "https://github.com/suprxyyaa/share_/blob/main/backend/app/services/admin_service.py"
click node_backend_data "https://github.com/suprxyyaa/share_/blob/main/backend/app/models/tables.py"
click node_backend_db "https://github.com/suprxyyaa/share_/blob/main/backend/app/db.py"
click node_backend_dep "https://github.com/suprxyyaa/share_/blob/main/backend/app/dependencies.py"
click node_start_sh "https://github.com/suprxyyaa/share_/blob/main/start.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_frontend_app,node_frontend_auth,node_frontend_patient,node_frontend_doctor,node_frontend_admin,node_frontend_lib toneBlue
class node_backend_app,node_backend_api,node_api_auth,node_api_doctors,node_api_appointments,node_api_files,node_api_admin,node_backend_services,node_svc_auth,node_svc_doctors,node_svc_appointments,node_svc_files,node_svc_authorize,node_svc_admin,node_backend_data,node_backend_db,node_backend_dep toneAmber
class node_cloudinary,node_postgres_neon,node_jitsi,node_start_sh toneMint
```

## Components

### Frontend

Next.js App Router UI split by user role and session helpers.

- [Next.js app](https://github.com/suprxyyaa/share_/tree/main/frontend/app): web frontend · Role-based App Router UI for patients, doctors, admins, and auth flows. · `frontend/app`
- [Auth UI](https://github.com/suprxyyaa/share_/tree/main/frontend/app/(auth)): route group · Login and registration screens for client-side session entry. · `frontend/app/(auth)`
- [Patient UI](https://github.com/suprxyyaa/share_/tree/main/frontend/app/(patient)): route group · Patient journey for discovery, booking, records, and payments. · `frontend/app/(patient)`
- [Doctor UI](https://github.com/suprxyyaa/share_/tree/main/frontend/app/(doctor)): route group · Doctor dashboard and availability management screens. · `frontend/app/(doctor)`
- [Admin UI](https://github.com/suprxyyaa/share_/tree/main/frontend/app/(admin)): route group · Admin verification and moderation screens. · `frontend/app/(admin)`
- [Client helpers](https://github.com/suprxyyaa/share_/tree/main/frontend/lib): session/http · Browser-side auth and API client helpers used across the UI. · `frontend/lib`

### Backend

FastAPI API, services, and PostgreSQL-backed persistence.

- [FastAPI app](https://github.com/suprxyyaa/share_/tree/main/backend/app): api backend · Backend application entrypoint and HTTP surface. · `backend/app`
- [API layer](https://github.com/suprxyyaa/share_/tree/main/backend/app/api): route handlers · Thin FastAPI route modules for each domain boundary. · `backend/app/api`
- [Auth API](https://github.com/suprxyyaa/share_/blob/main/backend/app/api/auth.py): routes · Register, login, and JWT-facing authentication endpoints. · `backend/app/api/auth.py`
- [Doctors API](https://github.com/suprxyyaa/share_/blob/main/backend/app/api/doctors.py): routes · Doctor registration, profile, approval, and availability endpoints. · `backend/app/api/doctors.py`
- [Appointments API](https://github.com/suprxyyaa/share_/blob/main/backend/app/api/appointments.py): routes · Booking and lifecycle endpoints for patient-doctor appointments. · `backend/app/api/appointments.py`
- [Files API](https://github.com/suprxyyaa/share_/blob/main/backend/app/api/files.py): routes · Upload, share, revoke, and access-check endpoints for medical files. · `backend/app/api/files.py`
- [Admin API](https://github.com/suprxyyaa/share_/blob/main/backend/app/api/admin.py): routes · Moderation endpoints for doctor verification and platform review. · `backend/app/api/admin.py`
- [Service layer](https://github.com/suprxyyaa/share_/tree/main/backend/app/services): business logic · Domain workflows that centralize rules and coordinate persistence. · `backend/app/services`
- [Auth service](https://github.com/suprxyyaa/share_/blob/main/backend/app/services/auth_service.py): jwt/users · User identity, registration, login, and credential workflows. · `backend/app/services/auth_service.py`
- [Doctor service](https://github.com/suprxyyaa/share_/blob/main/backend/app/services/doctor_service.py): profiles/approval · Doctor onboarding, verification, and availability workflows. · `backend/app/services/doctor_service.py`
- [Appointment service](https://github.com/suprxyyaa/share_/blob/main/backend/app/services/appointment_service.py): scheduling · Appointment booking, confirmation, cancellation, and meeting-link creation. · `backend/app/services/appointment_service.py`
- [File service](https://github.com/suprxyyaa/share_/blob/main/backend/app/services/file_service.py): storage/access · Cloudinary-backed upload and metadata coordination for medical files. · `backend/app/services/file_service.py`
- [Authorize](https://github.com/suprxyyaa/share_/blob/main/backend/app/services/authorize.py): access control · Single security boundary for file access decisions, expiries, revocation, and auditing. · `backend/app/services/authorize.py`
- [Admin service](https://github.com/suprxyyaa/share_/blob/main/backend/app/services/admin_service.py): moderation · Doctor review and administrative approval/rejection workflows. · `backend/app/services/admin_service.py`
- [PostgreSQL schema](https://github.com/suprxyyaa/share_/blob/main/backend/app/models/tables.py): relational model · System of record for users, roles, doctors, appointments, files, permissions, audits, and reviews. · `backend/app/models/tables.py`
- [DB wiring](https://github.com/suprxyyaa/share_/blob/main/backend/app/db.py): connection layer · Database engine/session wiring and request dependencies for the API. · `backend/app/db.py`
- [Dependencies](https://github.com/suprxyyaa/share_/blob/main/backend/app/dependencies.py): request context · FastAPI dependency wiring for auth, database, and request-scoped services. · `backend/app/dependencies.py`

### External systems

Third-party services and operational entrypoints.

- **Cloudinary**: external file store · Binary storage for uploaded medical records and doctor certificates.
- **Neon Postgres**: external database · Hosted PostgreSQL backing persistent platform state.
- **Jitsi links**: external meetings · Generated video visit links for scheduled appointments.
- [Start script](https://github.com/suprxyyaa/share_/blob/main/start.sh): local entrypoint · Development script that launches frontend and backend together. · `start.sh`

## Connections

- 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.
