# joannebrennanelliott/project_smart_parking architecture

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

- Interactive diagram: https://gitdiagram.com/joannebrennanelliott/project_smart_parking
- Repository: https://github.com/joannebrennanelliott/project_smart_parking

## Overview

1. **Overall shape**
   This repository is a small Node.js smart-parking system organized around a **gRPC backend**, a **browser-facing bridge**, and a **SQLite persistence layer**. The README describes higher-level parking features such as occupancy monitoring, pre-booking, alerts, and find-my-car, but the code layout shows the core architecture is service-driven rather than a monolithic web app.

2. **API contract**
   The main interface boundary is defined in `protos/smartparking.proto`. That file is the canonical contract for the system’s gRPC services and messages, and it is what ties the client side and server side together.

3. **Backend service**
   `server.js` is the backend service implementation. Based on the repo structure, it is likely the gRPC server that exposes parking-related operations such as bookings, user management, occupancy status, and logging. This is the central business-logic boundary.

4. **Bridge layer**
   `bridge.js` acts as the intermediary between the browser/UI and the gRPC backend. This is an important architectural seam: instead of the browser talking directly to gRPC, the bridge translates or proxies requests into the service layer, which is a common pattern when the UI is not gRPC-native.

5. **Browser UI**
   `index.html` is the main GUI entry point. `client_browser.js` appears to be the browser-side client logic that drives the interface and interacts with the bridge. This layer is responsible for presenting parking status, booking flows, and user-facing features like alerts or “find my car.”

6. **Non-browser client**
   `client.js` suggests there is also a direct Node.js client, likely for testing, administration, or command-line access to the gRPC service. This means the backend is not exclusively browser-driven; it supports at least one alternate consumer.

7. **Persistence layer**
   The `database/` directory contains SQLite schema and migration scripts, and there is a `users.db` file both at the repo root and under `database/`, indicating local embedded storage rather than a separate database service. The system persists users, bookings, and audit records in SQLite.

8. **Schema and migration management**
   Files such as `init_db.js`, `migrate_bookings.js`, `add_*_column.js`, `create_audit_log_table.js`, and `fix_audit_log_table.js` show the data model evolved over time through scripted migrations rather than a full ORM. `check_schema.sql` provides a schema verification step. This suggests the database is managed as a set of incremental local scripts.

9. **Audit and reporting**
   `view_audit_log.js`, `view_bookings.js`, and `view_users.js` are inspection/reporting utilities. They indicate the system keeps operational history, likely for admin visibility into user actions, booking changes, and access events. The audit log is a distinct concern from the transactional booking data.

10. **Data flow**
   The most likely end-to-end flow is: **browser UI → browser client → bridge → gRPC server → SQLite database**. Administrative or diagnostic flows can bypass the browser and go through `client.js` or the `view_*` scripts directly against the database.

11. **Feature boundaries**
   The README’s smart-parking features map cleanly to backend responsibilities:
   - **Occupancy monitoring**: backend state readout, likely exposed through gRPC
   - **Disabled-space pre-booking**: booking logic plus user/permit validation
   - **15/30-minute alerts**: time-based backend logic tied to booking or parking duration
   - **Parking location / find-my-car**: stored location metadata returned through service calls
   These are application features, not separate infrastructure modules in the tree.

12. **Architecture takeaway**
   This repo is best diagrammed as a **three-tier local system**: a browser UI, a Node.js bridge/service boundary, and a SQLite-backed gRPC backend. The proto file defines the service contract; the database scripts define the local persistence schema; and the view scripts provide operational/admin visibility into the stored parking data.

Main entry points: [`users.db`](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/users.db) (SQLite DB), [`bridge.js`](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/bridge.js) (Bridge), [`server.js`](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/server.js) (Backend Server), [`client.js`](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/client.js) (Node Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients & UI"]
  node_index_html["Browser UI<br/>ui entrypoint<br/>[index.html]"]
  node_client_browser["Browser Client<br/>[client_browser.js]"]
  node_bridge_js["Bridge<br/>proxy layer<br/>[bridge.js]"]
  node_client_js["Node Client<br/>[client.js]"]
end

subgraph group_service["Service Layer"]
  node_smartparking_proto["gRPC Contract<br/>proto schema<br/>[smartparking.proto]"]
  node_server_js["Backend Server<br/>gRPC service<br/>[server.js]"]
end

subgraph group_storage["Persistence"]
  node_init_db["DB Init<br/>schema bootstrap<br/>[init_db.js]"]
  node_migrate_bookings["Booking Migration<br/>schema migration"]
  node_db_changes["Schema Updates<br/>migration scripts"]
  node_audit_table["Audit Table<br/>schema script"]
  node_check_schema["Schema Check<br/>sql check<br/>[check_schema.sql]"]
  node_users_db[("SQLite DB<br/>embedded database<br/>[users.db]")]
end

subgraph group_ops["Ops & Reporting"]
  node_view_users["User Viewer<br/>reporting tool<br/>[view_users.js]"]
  node_view_bookings["Booking Viewer<br/>reporting tool<br/>[view_bookings.js]"]
  node_view_audit_log["Audit Viewer<br/>reporting tool<br/>[view_audit_log.js]"]
  node_db_view_bookings["DB Booking View<br/>reporting tool<br/>[view_bookings.js]"]
  node_db_view_users["DB User View<br/>reporting tool"]
end

node_index_html -->|"loads"| node_client_browser
node_client_browser -->|"calls"| node_bridge_js
node_bridge_js -->|"uses"| node_smartparking_proto
node_bridge_js -->|"proxies to"| node_server_js
node_client_js -->|"uses"| node_smartparking_proto
node_client_js -->|"calls"| node_server_js
node_server_js -->|"persists"| node_users_db
node_init_db -->|"initializes"| node_users_db
node_migrate_bookings -->|"migrates"| node_users_db
node_db_changes -->|"evolves"| node_users_db
node_audit_table -->|"creates"| node_users_db
node_check_schema -->|"verifies"| node_users_db
node_view_users -->|"reads"| node_users_db
node_view_bookings -->|"reads"| node_users_db
node_view_audit_log -->|"reads"| node_users_db
node_db_view_bookings -->|"reads"| node_users_db
node_db_view_users -->|"reads"| node_users_db

click node_index_html "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/index.html"
click node_client_browser "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/client_browser.js"
click node_bridge_js "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/bridge.js"
click node_client_js "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/client.js"
click node_smartparking_proto "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/protos/smartparking.proto"
click node_server_js "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/server.js"
click node_init_db "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/init_db.js"
click node_migrate_bookings "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/migrate_bookings.js"
click node_db_changes "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/add_disabledAccess_column.js"
click node_audit_table "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/create_audit_log_table.js"
click node_check_schema "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/check_schema.sql"
click node_users_db "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/users.db"
click node_view_users "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/view_users.js"
click node_view_bookings "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/view_bookings.js"
click node_view_audit_log "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/view_audit_log.js"
click node_db_view_bookings "https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/view_bookings.js"
click node_db_view_users "https://github.com/joannebrennanelliott/project_smart_parking/tree/main/database/view_users"

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_index_html,node_client_browser,node_bridge_js,node_client_js toneBlue
class node_smartparking_proto,node_server_js toneAmber
class node_init_db,node_migrate_bookings,node_db_changes,node_audit_table,node_check_schema,node_users_db toneMint
class node_view_users,node_view_bookings,node_view_audit_log,node_db_view_bookings,node_db_view_users toneRose
```

## Components

### Clients & UI

Browser and direct Node.js entry points that initiate parking workflows.

- [Browser UI](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/index.html): ui entrypoint · Main browser-facing interface for smart parking workflows. · `index.html`
- [Browser Client](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/client_browser.js): browser client · Client-side logic that talks through the bridge. · `client_browser.js`
- [Bridge](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/bridge.js): proxy layer · Translates browser requests into backend service calls. · `bridge.js`
- [Node Client](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/client.js): node client · Direct non-browser consumer of the parking service. · `client.js`

### Service Layer

gRPC contract and backend service implementation.

- [gRPC Contract](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/protos/smartparking.proto): proto schema · Canonical service and message definition for the system. · `protos/smartparking.proto`
- [Backend Server](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/server.js): gRPC service · Core parking service implementation and business logic boundary. · `server.js`

### Persistence

SQLite database and schema management scripts.

- [DB Init](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/init_db.js): schema bootstrap · Initial database creation and setup script. · `database/init_db.js`
- [Booking Migration](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/migrate_bookings.js): schema migration · Updates booking-related persistence structure. · `database/migrate_bookings.js`
- [Schema Updates](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/add_disabledAccess_column.js): migration scripts · Representative migration scripts for evolving user and booking fields. · `database/add_disabledAccess_column.js`
- [Audit Table](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/create_audit_log_table.js): schema script · Creates or repairs the audit log storage. · `database/create_audit_log_table.js`
- [Schema Check](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/check_schema.sql): sql check · Verifies the current database schema state. · `database/check_schema.sql`
- [SQLite DB](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/users.db): embedded database · Local persistent store for users, bookings, and audit records. · `users.db`

### Ops & Reporting

Utilities for inspecting operational data and records.

- [User Viewer](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/view_users.js): reporting tool · Inspects stored user records. · `view_users.js`
- [Booking Viewer](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/view_bookings.js): reporting tool · Inspects stored booking records. · `view_bookings.js`
- [Audit Viewer](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/view_audit_log.js): reporting tool · Inspects audit and activity history. · `database/view_audit_log.js`
- [DB Booking View](https://github.com/joannebrennanelliott/project_smart_parking/blob/main/database/view_bookings.js): reporting tool · Database-local booking inspection utility. · `database/view_bookings.js`
- [DB User View](https://github.com/joannebrennanelliott/project_smart_parking/tree/main/database/view_users): reporting tool · Database-local user inspection utility. · `database/view_users`

## Connections

- Browser UI → Browser Client: loads · The browser UI is driven by browser-side logic.
- Browser Client → Bridge: calls · Browser client sends requests through the bridge.
- Bridge → gRPC Contract: uses · Bridge follows the gRPC contract when calling the backend.
- Bridge → Backend Server: proxies to · Bridge forwards browser operations to the service.
- Node Client → gRPC Contract: uses · Direct Node client is shaped by the same proto contract.
- Node Client → Backend Server: calls · Node client can reach the backend directly.
- Backend Server → SQLite DB: persists · Backend reads and writes local parking data.
- DB Init → SQLite DB: initializes · Bootstrap script creates the embedded database.
- Booking Migration → SQLite DB: migrates · Booking schema changes are applied to the database.
- Schema Updates → SQLite DB: evolves · Incremental scripts add and adjust stored fields.
- Audit Table → SQLite DB: creates · Audit log structure is created or repaired in SQLite.
- Schema Check → SQLite DB: verifies · Schema check inspects database structure.
- User Viewer → SQLite DB: reads · User reporting utility reads from the database.
- Booking Viewer → SQLite DB: reads · Booking reporting utility reads from the database.
- Audit Viewer → SQLite DB: reads · Audit viewer reads history records from SQLite.
- DB Booking View → SQLite DB: reads · Database-local booking viewer reads the embedded store.
- DB User View → SQLite DB: reads · Database-local user viewer reads the embedded store.
