# berufsbildung-basel/parkit-service architecture

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

- Interactive diagram: https://gitdiagram.com/berufsbildung-basel/parkit-service
- Repository: https://github.com/berufsbildung-basel/parkit-service

## Overview

Parkit Service manages parking spots, vehicles, users, reservations, and billing. Users reserve spots through the web app or API; the reservation controller handles reservation actions and sends Slack notifications. Administrative and user billing surfaces manage invoices, while scheduled billing and invoice-status synchronization connect to CashCtrl. The graph includes documented billing capabilities and sampled controller behavior; unsampled billing-runner and route relationships are shown only as unverified where needed.

Main entry points: [`app/controllers/reservations_controller.rb`](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/reservations_controller.rb) (Reservation actions), [`app/services/cashctrl_client.rb`](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/services/cashctrl_client.rb) (CashCtrl client), [`app/controllers/admin/invoices_controller.rb`](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/admin/invoices_controller.rb) (Invoice administration), [`app/controllers/api/v1/parking_spots_controller.rb`](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/api/v1/parking_spots_controller.rb) (Availability API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and interfaces"]
  node_web["Web controllers"]
  node_api["Versioned API"]
  node_auth["Authentication"]
end

subgraph group_parking["Parking operations"]
  node_reservation["Reservation actions"]
  node_availability["Availability API"]
  node_reservation_model["Reservation rules<br/>[reservation.rb]"]
  node_reservation_validation["Reservation validation"]
  node_parking_data["Parking data<br/>[parking_spot.rb]"]
  node_browser["Reservation interface<br/>[main.js]"]
  node_database[("Application database<br/>[schema.rb]")]
end

subgraph group_billing["Billing"]
  node_admin_billing["Admin billing"]
  node_admin_invoices["Invoice administration"]
  node_user_billing["User billing"]
  node_billing_runner["Billing runner<br/>[billing_runner.rb]"]
  node_invoice_status["Invoice status sync"]
  node_invoice_job["Status sync job"]
  node_invoices["Invoice records<br/>[invoice.rb]"]
end

subgraph group_integrations["External integrations"]
  node_cashctrl_client["CashCtrl client<br/>[cashctrl_client.rb]"]
  node_cashctrl["CashCtrl"]
  node_slack["Slack"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_user -->|"calls"| node_api
node_user -->|"signs in"| node_auth
node_web -->|"routes to"| node_reservation
node_api -->|"routes to"| node_availability
node_reservation -->|"creates"| node_reservation_model
node_reservation -->|"notifies"| node_slack
node_reservation -.->|"renders form for"| node_browser
node_availability -->|"validates"| node_reservation_validation
node_availability -->|"queries"| node_parking_data
node_admin_billing -.->|"runs billing"| node_billing_runner
node_admin_invoices -->|"requests invoice actions"| node_cashctrl_client
node_admin_invoices -->|"refreshes status"| node_invoice_status
node_admin_invoices -->|"reads and updates"| node_invoices
node_user_billing -.->|"lists invoices"| node_invoices
node_invoice_job -.->|"runs sync"| node_invoice_status
node_invoice_status -.->|"reads remote status"| node_cashctrl_client
node_billing_runner -.->|"creates invoices"| node_cashctrl_client
node_cashctrl_client -->|"integrates with"| node_cashctrl

click node_web "https://github.com/berufsbildung-basel/parkit-service/tree/main/app/controllers"
click node_api "https://github.com/berufsbildung-basel/parkit-service/tree/main/app/controllers/api/v1"
click node_auth "https://github.com/berufsbildung-basel/parkit-service/tree/main/app/controllers/users"
click node_reservation "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/reservations_controller.rb"
click node_availability "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/api/v1/parking_spots_controller.rb"
click node_reservation_model "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/models/reservation.rb"
click node_reservation_validation "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/validators/reservation_validator.rb"
click node_parking_data "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/models/parking_spot.rb"
click node_browser "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/javascript/parking-spot-status/main.js"
click node_database "https://github.com/berufsbildung-basel/parkit-service/blob/main/db/schema.rb"
click node_admin_billing "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/admin/billing_controller.rb"
click node_admin_invoices "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/admin/invoices_controller.rb"
click node_user_billing "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/user_billing_controller.rb"
click node_billing_runner "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/services/billing_runner.rb"
click node_invoice_status "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/services/invoice_status_sync.rb"
click node_invoice_job "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/jobs/invoice_status_sync_job.rb"
click node_invoices "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/models/invoice.rb"
click node_cashctrl_client "https://github.com/berufsbildung-basel/parkit-service/blob/main/app/services/cashctrl_client.rb"

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_web,node_api,node_auth,node_user toneBlue
class node_reservation,node_availability,node_reservation_model,node_reservation_validation,node_parking_data,node_browser,node_database toneAmber
class node_admin_billing,node_admin_invoices,node_user_billing,node_billing_runner,node_invoice_status,node_invoice_job,node_invoices toneMint
class node_cashctrl_client,node_cashctrl,node_slack toneRose
```

## Components

### Access and interfaces

- [Web controllers](https://github.com/berufsbildung-basel/parkit-service/tree/main/app/controllers): `app/controllers`
- [Versioned API](https://github.com/berufsbildung-basel/parkit-service/tree/main/app/controllers/api/v1): `app/controllers/api/v1`
- [Authentication](https://github.com/berufsbildung-basel/parkit-service/tree/main/app/controllers/users): `app/controllers/users`

### Parking operations

- [Reservation actions](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/reservations_controller.rb): `app/controllers/reservations_controller.rb`
- [Availability API](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/api/v1/parking_spots_controller.rb): `app/controllers/api/v1/parking_spots_controller.rb`
- [Reservation rules](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/models/reservation.rb): `app/models/reservation.rb`
- [Reservation validation](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/validators/reservation_validator.rb): `app/validators/reservation_validator.rb`
- [Parking data](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/models/parking_spot.rb): `app/models/parking_spot.rb`
- [Reservation interface](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/javascript/parking-spot-status/main.js): `app/javascript/parking-spot-status/main.js`
- [Application database](https://github.com/berufsbildung-basel/parkit-service/blob/main/db/schema.rb): `db/schema.rb`

### Billing

- [Admin billing](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/admin/billing_controller.rb): `app/controllers/admin/billing_controller.rb`
- [Invoice administration](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/admin/invoices_controller.rb): `app/controllers/admin/invoices_controller.rb`
- [User billing](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/controllers/user_billing_controller.rb): `app/controllers/user_billing_controller.rb`
- [Billing runner](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/services/billing_runner.rb): `app/services/billing_runner.rb`
- [Invoice status sync](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/services/invoice_status_sync.rb): `app/services/invoice_status_sync.rb`
- [Status sync job](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/jobs/invoice_status_sync_job.rb): `app/jobs/invoice_status_sync_job.rb`
- [Invoice records](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/models/invoice.rb): `app/models/invoice.rb`

### External integrations

- [CashCtrl client](https://github.com/berufsbildung-basel/parkit-service/blob/main/app/services/cashctrl_client.rb): `app/services/cashctrl_client.rb`
- **CashCtrl**
- **Slack**

### Other components

- **User**

## Connections

- User → Web controllers: uses
- User → Versioned API: calls
- User → Authentication: signs in
- Web controllers → Reservation actions: routes to
- Versioned API → Availability API: routes to
- Reservation actions → Reservation rules: creates (evidence: `app/controllers/reservations_controller.rb`)
- Reservation actions → Slack: notifies (evidence: `app/controllers/reservations_controller.rb`)
- Reservation actions → Reservation interface: renders form for
- Availability API → Reservation validation: validates (evidence: `app/controllers/api/v1/parking_spots_controller.rb`)
- Availability API → Parking data: queries (evidence: `app/controllers/api/v1/parking_spots_controller.rb`)
- Admin billing → Billing runner: runs billing
- Invoice administration → CashCtrl client: requests invoice actions (evidence: `app/controllers/admin/invoices_controller.rb`)
- Invoice administration → Invoice status sync: refreshes status (evidence: `app/controllers/admin/invoices_controller.rb`)
- Invoice administration → Invoice records: reads and updates (evidence: `app/controllers/admin/invoices_controller.rb`)
- User billing → Invoice records: lists invoices
- Status sync job → Invoice status sync: runs sync
- Invoice status sync → CashCtrl client: reads remote status
- Billing runner → CashCtrl client: creates invoices
- CashCtrl client → CashCtrl: integrates with