# bkuroko/parkfinder2 architecture

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

- Interactive diagram: https://gitdiagram.com/bkuroko/parkfinder2
- Repository: https://github.com/bkuroko/parkfinder2

## Overview

ParkFinder’s main flow detects parking-slot occupancy from video, ingests updates through FastAPI, stores facility and occupancy state in PostgreSQL, and presents availability to drivers and administrators. Admin workflows also cover authentication, metrics, logs, reports, and parking-lot submissions. The README documents an optional Appwrite-backed API migration. Some UI and route relationships are documented rather than shown in excerpts; those links cite the README, and the Appwrite integration is kept separate.

Main entry points: [`backend/app/api/routes/ingest.py`](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/ingest.py) (AI ingestion), [`mobile/src/api/client.js`](https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/api/client.js) (Mobile API client), [`backend/app/main.py`](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/main.py) (FastAPI entry), [`web-admin/src/api/client.js`](https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/api/client.js) (Admin API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Video detection"]
  node_yolo["Slot detector<br/>[detector.py]"]
end

subgraph group_backend["API and domain"]
  node_api["FastAPI entry<br/>[main.py]"]
  node_public["Public facilities<br/>[public.py]"]
  node_auth["Admin auth<br/>[auth.py]"]
  node_admin_routes["Admin operations<br/>[admin.py]"]
  node_ingest["AI ingestion<br/>[ingest.py]"]
  node_access["Access control<br/>[deps.py]"]
  node_security["JWT security<br/>[security.py]"]
  node_services["Occupancy services<br/>[services.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_appwrite["Appwrite function<br/>[main.py]"]
end

subgraph group_storage["Parking data"]
  node_models["Parking models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
  node_tablesdb[("Appwrite TablesDB")]
end

subgraph group_driver["Driver app"]
  node_mobile_app["Mobile navigation<br/>[App.js]"]
  node_mobile_search["Facility search"]
  node_mobile_map["Facility map"]
  node_mobile_details["Facility details"]
  node_mobile_location["Location map"]
  node_mobile_client["Mobile API client<br/>[client.js]"]
end

subgraph group_admin["Admin dashboard"]
  node_web_app["Admin app<br/>[App.jsx]"]
  node_login["Admin login<br/>[LoginPage.jsx]"]
  node_dashboard["Admin dashboard<br/>[DashboardPage.jsx]"]
  node_web_client["Admin API client<br/>[client.js]"]
end

node_video["Parking video"]
node_api_actor(("AI processor"))

node_video -->|"provides footage"| node_yolo
node_yolo -->|"detects slots"| node_api_actor
node_api_actor -->|"posts updates"| node_ingest
node_api -->|"registers routes"| node_public
node_api -->|"registers routes"| node_auth
node_api -->|"registers routes"| node_admin_routes
node_api -->|"registers routes"| node_ingest
node_ingest -->|"checks ingest key"| node_access
node_auth -->|"requires admin"| node_access
node_access -->|"validates JWT"| node_security
node_ingest -->|"updates occupancy"| node_services
node_public -->|"builds facility views"| node_services
node_admin_routes -->|"builds metrics"| node_services
node_ingest -->|"records slot state"| node_models
node_services -->|"queries parking data"| node_models
node_models -->|"persists records"| node_postgres
node_mobile_app -->|"opens map"| node_mobile_map
node_mobile_app -->|"opens facility"| node_mobile_details
node_mobile_app -->|"opens location"| node_mobile_location
node_mobile_search -->|"requests facilities"| node_mobile_client
node_mobile_map -->|"loads facilities"| node_mobile_client
node_mobile_details -->|"loads details"| node_mobile_client
node_mobile_location -->|"loads location data"| node_mobile_client
node_mobile_client -->|"calls public API"| node_public
node_web_app -->|"shows unauthenticated"| node_login
node_web_app -->|"shows authenticated"| node_dashboard
node_login -->|"submits credentials"| node_web_client
node_dashboard -->|"loads admin data"| node_web_client
node_web_client -->|"calls login and profile"| node_auth
node_web_client -->|"calls admin endpoints"| node_admin_routes
node_appwrite -.->|"stores API data"| node_tablesdb

click node_yolo "https://github.com/bkuroko/parkfinder2/blob/main/ai_processing/detector.py"
click node_api "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/main.py"
click node_public "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/public.py"
click node_auth "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/auth.py"
click node_admin_routes "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/admin.py"
click node_ingest "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/ingest.py"
click node_access "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/deps.py"
click node_security "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/core/security.py"
click node_services "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/services.py"
click node_schemas "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/schemas.py"
click node_models "https://github.com/bkuroko/parkfinder2/blob/main/backend/app/models.py"
click node_mobile_app "https://github.com/bkuroko/parkfinder2/blob/main/mobile/App.js"
click node_mobile_search "https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilitySearchScreen.js"
click node_mobile_map "https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilityMapScreen.js"
click node_mobile_details "https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilityDetailsScreen.js"
click node_mobile_location "https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilityLocationScreen.js"
click node_mobile_client "https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/api/client.js"
click node_web_app "https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/App.jsx"
click node_login "https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/pages/LoginPage.jsx"
click node_dashboard "https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/pages/DashboardPage.jsx"
click node_web_client "https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/api/client.js"
click node_appwrite "https://github.com/bkuroko/parkfinder2/blob/main/appwrite/functions/parkfinder-api/src/main.py"

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_yolo toneBlue
class node_api,node_public,node_auth,node_admin_routes,node_ingest,node_access,node_security,node_services,node_schemas,node_appwrite toneAmber
class node_models,node_postgres,node_tablesdb toneMint
class node_mobile_app,node_mobile_search,node_mobile_map,node_mobile_details,node_mobile_location,node_mobile_client toneRose
class node_web_app,node_login,node_dashboard,node_web_client,node_video,node_api_actor toneIndigo
```

## Components

### Video detection

- [Slot detector](https://github.com/bkuroko/parkfinder2/blob/main/ai_processing/detector.py): `ai_processing/detector.py`

### API and domain

- [FastAPI entry](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/main.py): `backend/app/main.py`
- [Public facilities](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/public.py): `backend/app/api/routes/public.py`
- [Admin auth](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [Admin operations](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/admin.py): `backend/app/api/routes/admin.py`
- [AI ingestion](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/routes/ingest.py): `backend/app/api/routes/ingest.py`
- [Access control](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [JWT security](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Occupancy services](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/services.py): `backend/app/services.py`
- [API schemas](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Appwrite function](https://github.com/bkuroko/parkfinder2/blob/main/appwrite/functions/parkfinder-api/src/main.py): `appwrite/functions/parkfinder-api/src/main.py`

### Parking data

- [Parking models](https://github.com/bkuroko/parkfinder2/blob/main/backend/app/models.py): `backend/app/models.py`
- **PostgreSQL**
- **Appwrite TablesDB**

### Driver app

- [Mobile navigation](https://github.com/bkuroko/parkfinder2/blob/main/mobile/App.js): `mobile/App.js`
- [Facility search](https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilitySearchScreen.js): `mobile/src/screens/FacilitySearchScreen.js`
- [Facility map](https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilityMapScreen.js): `mobile/src/screens/FacilityMapScreen.js`
- [Facility details](https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilityDetailsScreen.js): `mobile/src/screens/FacilityDetailsScreen.js`
- [Location map](https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/screens/FacilityLocationScreen.js): `mobile/src/screens/FacilityLocationScreen.js`
- [Mobile API client](https://github.com/bkuroko/parkfinder2/blob/main/mobile/src/api/client.js): `mobile/src/api/client.js`

### Admin dashboard

- [Admin app](https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/App.jsx): `web-admin/src/App.jsx`
- [Admin login](https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/pages/LoginPage.jsx): `web-admin/src/pages/LoginPage.jsx`
- [Admin dashboard](https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/pages/DashboardPage.jsx): `web-admin/src/pages/DashboardPage.jsx`
- [Admin API client](https://github.com/bkuroko/parkfinder2/blob/main/web-admin/src/api/client.js): `web-admin/src/api/client.js`

### Other components

- **Parking video**
- **AI processor**

## Connections

- Parking video → Slot detector: provides footage
- Slot detector → AI processor: detects slots
- AI processor → AI ingestion: posts updates
- FastAPI entry → Public facilities: registers routes (evidence: `backend/app/main.py`)
- FastAPI entry → Admin auth: registers routes (evidence: `backend/app/main.py`)
- FastAPI entry → Admin operations: registers routes (evidence: `backend/app/main.py`)
- FastAPI entry → AI ingestion: registers routes (evidence: `backend/app/main.py`)
- AI ingestion → Access control: checks ingest key (evidence: `backend/app/api/routes/ingest.py`)
- Admin auth → Access control: requires admin (evidence: `backend/app/api/routes/auth.py`)
- Access control → JWT security: validates JWT (evidence: `backend/app/api/deps.py`)
- AI ingestion → Occupancy services: updates occupancy (evidence: `backend/app/api/routes/ingest.py`)
- Public facilities → Occupancy services: builds facility views (evidence: `backend/app/api/routes/public.py`)
- Admin operations → Occupancy services: builds metrics (evidence: `backend/app/api/routes/admin.py`)
- AI ingestion → Parking models: records slot state (evidence: `backend/app/api/routes/ingest.py`)
- Occupancy services → Parking models: queries parking data (evidence: `backend/app/services.py`)
- Parking models → PostgreSQL: persists records (evidence: `backend/app/models.py`)
- Mobile navigation → Facility map: opens map (evidence: `mobile/App.js`)
- Mobile navigation → Facility details: opens facility (evidence: `mobile/App.js`)
- Mobile navigation → Location map: opens location (evidence: `mobile/App.js`)
- Facility search → Mobile API client: requests facilities (evidence: `mobile/src/screens/FacilitySearchScreen.js`)
- Facility map → Mobile API client: loads facilities (evidence: `mobile/src/screens/FacilityMapScreen.js`)
- Facility details → Mobile API client: loads details (evidence: `mobile/src/screens/FacilityDetailsScreen.js`)
- Location map → Mobile API client: loads location data (evidence: `mobile/src/screens/FacilityLocationScreen.js`)
- Mobile API client → Public facilities: calls public API
- Admin app → Admin login: shows unauthenticated (evidence: `web-admin/src/App.jsx`)
- Admin app → Admin dashboard: shows authenticated (evidence: `web-admin/src/App.jsx`)
- Admin login → Admin API client: submits credentials (evidence: `web-admin/src/pages/LoginPage.jsx`)
- Admin dashboard → Admin API client: loads admin data (evidence: `web-admin/src/pages/DashboardPage.jsx`)
- Admin API client → Admin auth: calls login and profile
- Admin API client → Admin operations: calls admin endpoints
- Appwrite function → Appwrite TablesDB: stores API data