# veletpro0-lgtm/valet-platform architecture

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

- Interactive diagram: https://gitdiagram.com/veletpro0-lgtm/valet-platform
- Repository: https://github.com/veletpro0-lgtm/valet-platform
- Video tour (about a minute): https://gitdiagram.com/veletpro0-lgtm/valet-platform/video

## Overview

VAYLET is a multi-tenant valet operations platform. Its core workflow spans vehicle check-in and parking, task assignment, guest retrieval requests, staff retrieval and handoff, with payment and custody/audit capabilities alongside it. Staff, guests, and managers use the API through separate domain surfaces; management also provides configuration, analytics, and reports. The graph reflects documented capabilities and sampled API code; unsampled subsystem wiring is represented conservatively, without implying unverified internal calls.

Main entry points: [`apps/api/src/common/database/postgres.ts`](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/common/database/postgres.ts) (PostgreSQL), [`apps/api/src/modules/auth/mfa/staff-mfa.controller.ts`](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/auth/mfa/staff-mfa.controller.ts) (MFA), [`apps/api/src/modules/retrieval/start-retrieval.controller.ts`](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/retrieval/start-retrieval.controller.ts) (Staff retrieval), [`apps/api/src/modules/tracking/gps-ingestion.controller.ts`](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/tracking/gps-ingestion.controller.ts) (Task tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity and access"]
  node_staff_auth["Staff authentication"]
  node_mfa["MFA"]
end

subgraph group_operations["Valet operations"]
  node_checkin["Vehicle check-in"]
  node_ocr["Plate OCR"]
  node_parking["Parking custody"]
  node_keys["Key custody"]
  node_dispatch["Task dispatch"]
  node_retrieval["Staff retrieval"]
  node_handoff["Vehicle handoff"]
  node_tracking["Task tracking"]
  node_incidents["Incident reporting"]
end

subgraph group_guest_money["Guest and payment"]
  node_guest_access["Guest access"]
  node_guest_retrieval["Guest retrieval request"]
  node_payments["Payments and cash"]
end

subgraph group_management["Management surfaces"]
  node_dashboard["Operations dashboard"]
  node_analytics["Analytics and reports"]
  node_configuration["Management configuration"]
  node_staff_admin["Staff management"]
end

subgraph group_platform["Shared platform"]
  node_audit["Audit events"]
  node_postgres[("PostgreSQL<br/>[postgres.ts]")]
end

node_staff(("Staff"))
node_guest(("Guest"))
node_manager(("Manager"))

node_staff -->|"authenticates"| node_staff_auth
node_staff -->|"verifies factor"| node_mfa
node_staff -->|"checks in vehicle"| node_checkin
node_staff -->|"assists plate entry"| node_ocr
node_staff -->|"records parking"| node_parking
node_staff -->|"records custody"| node_keys
node_staff -->|"handles tasks"| node_dispatch
node_staff -->|"retrieves vehicle"| node_retrieval
node_staff -->|"completes handoff"| node_handoff
node_staff -->|"sends GPS samples"| node_tracking
node_guest -->|"opens secure link"| node_guest_access
node_guest -->|"requests retrieval"| node_guest_retrieval
node_guest -->|"pays or validates"| node_payments
node_manager -->|"views operations"| node_dashboard
node_manager -->|"reviews reports"| node_analytics
node_manager -->|"configures location"| node_configuration
node_manager -->|"manages staff"| node_staff_admin
node_manager -->|"reports incident"| node_incidents
node_guest_retrieval -->|"reads and writes"| node_postgres
node_retrieval -->|"reads and writes"| node_postgres
node_tracking -->|"ingests samples"| node_postgres
node_mfa -->|"stores factor state"| node_postgres
node_mfa -->|"records activation"| node_audit
node_dashboard -->|"queries task queues"| node_postgres

click node_staff_auth "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/auth/staff-auth.controller.ts"
click node_mfa "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/auth/mfa/staff-mfa.controller.ts"
click node_checkin "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/check-in-api/check-in-api.controller.ts"
click node_ocr "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/check-in-api/plate-ocr.controller.ts"
click node_parking "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/parking/start-parking.controller.ts"
click node_keys "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/keys/key-custody.controller.ts"
click node_dispatch "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/dispatch/dispatch.controller.ts"
click node_retrieval "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/retrieval/start-retrieval.controller.ts"
click node_handoff "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/retrieval/complete-handoff.controller.ts"
click node_tracking "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/tracking/gps-ingestion.controller.ts"
click node_guest_access "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/guest-access/guest-access.controller.ts"
click node_guest_retrieval "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/retrieval/guest-retrieval.controller.ts"
click node_payments "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/payments/guest-payment.controller.ts"
click node_incidents "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/incidents/incident-reporting.controller.ts"
click node_dashboard "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/dashboard/overview.controller.ts"
click node_analytics "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/dashboard/analytics.controller.ts"
click node_configuration "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/management/management-settings.controller.ts"
click node_staff_admin "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/management/staff-management.controller.ts"
click node_audit "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/audit/custody-audit-event-writer.ts"
click node_postgres "https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/common/database/postgres.ts"

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_staff_auth,node_mfa toneBlue
class node_checkin,node_ocr,node_parking,node_keys,node_dispatch,node_retrieval,node_handoff,node_tracking,node_incidents toneAmber
class node_guest_access,node_guest_retrieval,node_payments toneMint
class node_dashboard,node_analytics,node_configuration,node_staff_admin toneRose
class node_audit,node_postgres,node_staff,node_guest,node_manager toneIndigo
```

## Components

### Identity and access

- [Staff authentication](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/auth/staff-auth.controller.ts): `apps/api/src/modules/auth/staff-auth.controller.ts`
- [MFA](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/auth/mfa/staff-mfa.controller.ts): `apps/api/src/modules/auth/mfa/staff-mfa.controller.ts`

### Valet operations

- [Vehicle check-in](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/check-in-api/check-in-api.controller.ts): `apps/api/src/modules/check-in-api/check-in-api.controller.ts`
- [Plate OCR](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/check-in-api/plate-ocr.controller.ts): `apps/api/src/modules/check-in-api/plate-ocr.controller.ts`
- [Parking custody](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/parking/start-parking.controller.ts): `apps/api/src/modules/parking/start-parking.controller.ts`
- [Key custody](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/keys/key-custody.controller.ts): `apps/api/src/modules/keys/key-custody.controller.ts`
- [Task dispatch](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/dispatch/dispatch.controller.ts): `apps/api/src/modules/dispatch/dispatch.controller.ts`
- [Staff retrieval](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/retrieval/start-retrieval.controller.ts): `apps/api/src/modules/retrieval/start-retrieval.controller.ts`
- [Vehicle handoff](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/retrieval/complete-handoff.controller.ts): `apps/api/src/modules/retrieval/complete-handoff.controller.ts`
- [Task tracking](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/tracking/gps-ingestion.controller.ts): `apps/api/src/modules/tracking/gps-ingestion.controller.ts`
- [Incident reporting](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/incidents/incident-reporting.controller.ts): `apps/api/src/modules/incidents/incident-reporting.controller.ts`

### Guest and payment

- [Guest access](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/guest-access/guest-access.controller.ts): `apps/api/src/modules/guest-access/guest-access.controller.ts`
- [Guest retrieval request](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/retrieval/guest-retrieval.controller.ts): `apps/api/src/modules/retrieval/guest-retrieval.controller.ts`
- [Payments and cash](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/payments/guest-payment.controller.ts): `apps/api/src/modules/payments/guest-payment.controller.ts`

### Management surfaces

- [Operations dashboard](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/dashboard/overview.controller.ts): `apps/api/src/modules/dashboard/overview.controller.ts`
- [Analytics and reports](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/dashboard/analytics.controller.ts): `apps/api/src/modules/dashboard/analytics.controller.ts`
- [Management configuration](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/management/management-settings.controller.ts): `apps/api/src/modules/management/management-settings.controller.ts`
- [Staff management](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/management/staff-management.controller.ts): `apps/api/src/modules/management/staff-management.controller.ts`

### Shared platform

- [Audit events](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/modules/audit/custody-audit-event-writer.ts): `apps/api/src/modules/audit/custody-audit-event-writer.ts`
- [PostgreSQL](https://github.com/veletpro0-lgtm/valet-platform/blob/main/apps/api/src/common/database/postgres.ts): `apps/api/src/common/database/postgres.ts`

### Other components

- **Staff**
- **Guest**
- **Manager**

## Connections

- Staff → Staff authentication: authenticates
- Staff → MFA: verifies factor
- Staff → Vehicle check-in: checks in vehicle
- Staff → Plate OCR: assists plate entry
- Staff → Parking custody: records parking
- Staff → Key custody: records custody
- Staff → Task dispatch: handles tasks
- Staff → Staff retrieval: retrieves vehicle
- Staff → Vehicle handoff: completes handoff
- Staff → Task tracking: sends GPS samples
- Guest → Guest access: opens secure link
- Guest → Guest retrieval request: requests retrieval
- Guest → Payments and cash: pays or validates
- Manager → Operations dashboard: views operations
- Manager → Analytics and reports: reviews reports
- Manager → Management configuration: configures location
- Manager → Staff management: manages staff
- Manager → Incident reporting: reports incident
- Guest retrieval request → PostgreSQL: reads and writes
- Staff retrieval → PostgreSQL: reads and writes
- Task tracking → PostgreSQL: ingests samples
- MFA → PostgreSQL: stores factor state
- MFA → Audit events: records activation
- Operations dashboard → PostgreSQL: queries task queues