# othoth77/idauto architecture

> Architecture diagram of the GitHub repository othoth77/idauto, 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/othoth77/idauto
- Repository: https://github.com/othoth77/idauto

## Overview

IDauto is a vehicle-identity and history reference implementation. The citizen-facing path captures a plate, resolves it to an identity (IVID), and presents a passport; the authenticated workspace supports manual registration, vehicle dossiers, owner contacts, interventions, parts, and workshop operations. Supporting layers normalize and resolve vehicle identifiers, persist records and evidence, and audit mutations. The README also describes ingestion/review and operator capabilities, but their runtime wiring is not shown here. Edges reflect sampled calls, indexed references, or explicit README statements; unsampled connections are omitted.

Main entry points: [`reference/db.js`](https://github.com/othoth77/idauto/blob/main/reference/db.js) (PostgreSQL), [`reference/vehicle/vehicle-repository.js`](https://github.com/othoth77/idauto/blob/main/reference/vehicle/vehicle-repository.js) (Vehicle repository), [`reference/workspace-routes.js`](https://github.com/othoth77/idauto/blob/main/reference/workspace-routes.js) (Workspace routes), [`reference/writes.js`](https://github.com/othoth77/idauto/blob/main/reference/writes.js) (Audited writes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen passport"]
  node_scanner["Plate scanner<br/>[plate-scanner.js]"]
  node_publicpages["Passport pages<br/>[passport.js]"]
  node_publicapi["Public API<br/>[api.js]"]
end

subgraph group_workspace["Workspace operations"]
  node_workspaceclient["Workspace UI<br/>[app-vehicles.js]"]
  node_workroutes["Workspace routes"]
  node_registration["Manual registration"]
  node_workrepo["Workspace reads"]
  node_ownercontacts["Owner contacts<br/>[owner-contacts.js]"]
  node_interventions["Interventions"]
end

subgraph group_vehicle["Vehicle identity"]
  node_v12routes["Identification routes<br/>[v12-routes.js]"]
  node_resolver["Vehicle resolver"]
  node_normalizer["Plate normalizer"]
  node_vehicledata["Vehicle repository"]
  node_workshop["Workshop service"]
  node_parts["Parts catalogue<br/>[parts-catalog.js]"]
  node_localparts["Local parts"]
end

subgraph group_platform["Persistence and evidence"]
  node_documents["Document service"]
  node_docrepo["Document records"]
  node_storage["Media storage<br/>[storage.js]"]
  node_writes["Audited writes<br/>[writes.js]"]
  node_db[("PostgreSQL<br/>[db.js]")]
  node_ingestion["Community ingestion<br/>[ingestion.js]"]
  node_adminrepo["Admin read model"]
end

node_citizen(("Citizen"))

node_citizen -->|"scans plate"| node_scanner
node_scanner -.->|"submits plate"| node_publicapi
node_publicapi -->|"serves passport"| node_publicpages
node_workspaceclient -.->|"uses API"| node_workroutes
node_workroutes -->|"registers vehicle"| node_registration
node_workroutes -->|"reads workspace"| node_workrepo
node_workroutes -->|"manages contacts"| node_ownercontacts
node_workroutes -->|"manages repairs"| node_interventions
node_registration -->|"creates identity"| node_vehicledata
node_registration -->|"records owner"| node_ownercontacts
node_registration -->|"audits mutation"| node_writes
node_v12routes -->|"resolves vehicle"| node_resolver
node_v12routes -->|"queries parts"| node_parts
node_v12routes -->|"handles workshop"| node_workshop
node_resolver -->|"normalizes plate"| node_normalizer
node_resolver -->|"looks up vehicle"| node_vehicledata
node_workshop -->|"uses identity"| node_vehicledata
node_parts -->|"queries catalogue"| node_localparts
node_documents -->|"stores metadata"| node_docrepo
node_documents -->|"stores media"| node_storage
node_docrepo -->|"reads and writes"| node_db
node_vehicledata -->|"reads and writes"| node_db
node_vehicledata -->|"audits changes"| node_writes
node_localparts -->|"queries catalogue"| node_db
node_localparts -->|"audits changes"| node_writes
node_workrepo -->|"reads records"| node_vehicledata
node_workrepo -->|"queries workspace"| node_db
node_ownercontacts -->|"persists contacts"| node_db
node_interventions -->|"uses vehicle"| node_vehicledata
node_interventions -->|"persists repairs"| node_db
node_writes -->|"commits audit"| node_db
node_writes -->|"cleans media"| node_storage
node_adminrepo -->|"queries registry"| node_db

click node_scanner "https://github.com/othoth77/idauto/blob/main/web/citizen/plate-scanner.js"
click node_publicpages "https://github.com/othoth77/idauto/blob/main/web/citizen/passport.js"
click node_publicapi "https://github.com/othoth77/idauto/blob/main/reference/api.js"
click node_workspaceclient "https://github.com/othoth77/idauto/blob/main/reference/app-vehicles.js"
click node_workroutes "https://github.com/othoth77/idauto/blob/main/reference/workspace-routes.js"
click node_registration "https://github.com/othoth77/idauto/blob/main/reference/workspace/registration-service.js"
click node_workrepo "https://github.com/othoth77/idauto/blob/main/reference/workspace/workspace-repository.js"
click node_ownercontacts "https://github.com/othoth77/idauto/blob/main/reference/workspace/owner-contacts.js"
click node_interventions "https://github.com/othoth77/idauto/blob/main/reference/workspace/intervention-service.js"
click node_v12routes "https://github.com/othoth77/idauto/blob/main/reference/v12-routes.js"
click node_resolver "https://github.com/othoth77/idauto/blob/main/reference/vehicle/vehicle-resolver.js"
click node_normalizer "https://github.com/othoth77/idauto/blob/main/reference/vehicle/plate-normalizer.js"
click node_vehicledata "https://github.com/othoth77/idauto/blob/main/reference/vehicle/vehicle-repository.js"
click node_workshop "https://github.com/othoth77/idauto/blob/main/reference/workshop/workshop-vehicle-service.js"
click node_parts "https://github.com/othoth77/idauto/blob/main/reference/parts/parts-catalog.js"
click node_localparts "https://github.com/othoth77/idauto/blob/main/reference/parts/local-parts-catalog.js"
click node_documents "https://github.com/othoth77/idauto/blob/main/reference/documents/document-service.js"
click node_docrepo "https://github.com/othoth77/idauto/blob/main/reference/documents/document-repository.js"
click node_storage "https://github.com/othoth77/idauto/blob/main/reference/storage.js"
click node_writes "https://github.com/othoth77/idauto/blob/main/reference/writes.js"
click node_db "https://github.com/othoth77/idauto/blob/main/reference/db.js"
click node_ingestion "https://github.com/othoth77/idauto/blob/main/reference/ingestion.js"
click node_adminrepo "https://github.com/othoth77/idauto/blob/main/reference/admin/admin-repository.js"

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_scanner,node_publicpages,node_publicapi toneBlue
class node_workspaceclient,node_workroutes,node_registration,node_workrepo,node_ownercontacts,node_interventions toneAmber
class node_v12routes,node_resolver,node_normalizer,node_vehicledata,node_workshop,node_parts,node_localparts toneMint
class node_documents,node_docrepo,node_storage,node_writes,node_db,node_ingestion,node_adminrepo toneRose
class node_citizen toneIndigo
```

## Components

### Citizen passport

- [Plate scanner](https://github.com/othoth77/idauto/blob/main/web/citizen/plate-scanner.js): `web/citizen/plate-scanner.js`
- [Passport pages](https://github.com/othoth77/idauto/blob/main/web/citizen/passport.js): `web/citizen/passport.js`
- [Public API](https://github.com/othoth77/idauto/blob/main/reference/api.js): `reference/api.js`

### Workspace operations

- [Workspace UI](https://github.com/othoth77/idauto/blob/main/reference/app-vehicles.js): `reference/app-vehicles.js`
- [Workspace routes](https://github.com/othoth77/idauto/blob/main/reference/workspace-routes.js): `reference/workspace-routes.js`
- [Manual registration](https://github.com/othoth77/idauto/blob/main/reference/workspace/registration-service.js): `reference/workspace/registration-service.js`
- [Workspace reads](https://github.com/othoth77/idauto/blob/main/reference/workspace/workspace-repository.js): `reference/workspace/workspace-repository.js`
- [Owner contacts](https://github.com/othoth77/idauto/blob/main/reference/workspace/owner-contacts.js): `reference/workspace/owner-contacts.js`
- [Interventions](https://github.com/othoth77/idauto/blob/main/reference/workspace/intervention-service.js): `reference/workspace/intervention-service.js`

### Vehicle identity

- [Identification routes](https://github.com/othoth77/idauto/blob/main/reference/v12-routes.js): `reference/v12-routes.js`
- [Vehicle resolver](https://github.com/othoth77/idauto/blob/main/reference/vehicle/vehicle-resolver.js): `reference/vehicle/vehicle-resolver.js`
- [Plate normalizer](https://github.com/othoth77/idauto/blob/main/reference/vehicle/plate-normalizer.js): `reference/vehicle/plate-normalizer.js`
- [Vehicle repository](https://github.com/othoth77/idauto/blob/main/reference/vehicle/vehicle-repository.js): `reference/vehicle/vehicle-repository.js`
- [Workshop service](https://github.com/othoth77/idauto/blob/main/reference/workshop/workshop-vehicle-service.js): `reference/workshop/workshop-vehicle-service.js`
- [Parts catalogue](https://github.com/othoth77/idauto/blob/main/reference/parts/parts-catalog.js): `reference/parts/parts-catalog.js`
- [Local parts](https://github.com/othoth77/idauto/blob/main/reference/parts/local-parts-catalog.js): `reference/parts/local-parts-catalog.js`

### Persistence and evidence

- [Document service](https://github.com/othoth77/idauto/blob/main/reference/documents/document-service.js): `reference/documents/document-service.js`
- [Document records](https://github.com/othoth77/idauto/blob/main/reference/documents/document-repository.js): `reference/documents/document-repository.js`
- [Media storage](https://github.com/othoth77/idauto/blob/main/reference/storage.js): `reference/storage.js`
- [Audited writes](https://github.com/othoth77/idauto/blob/main/reference/writes.js): `reference/writes.js`
- [PostgreSQL](https://github.com/othoth77/idauto/blob/main/reference/db.js): `reference/db.js`
- [Community ingestion](https://github.com/othoth77/idauto/blob/main/reference/ingestion.js): `reference/ingestion.js`
- [Admin read model](https://github.com/othoth77/idauto/blob/main/reference/admin/admin-repository.js): `reference/admin/admin-repository.js`

### Other components

- **Citizen**

## Connections

- Citizen → Plate scanner: scans plate (evidence: `README.md`)
- Plate scanner → Public API: submits plate
- Public API → Passport pages: serves passport (evidence: `README.md`)
- Workspace UI → Workspace routes: uses API
- Workspace routes → Manual registration: registers vehicle (evidence: `reference/workspace-routes.js`)
- Workspace routes → Workspace reads: reads workspace (evidence: `reference/workspace-routes.js`)
- Workspace routes → Owner contacts: manages contacts (evidence: `reference/workspace-routes.js`)
- Workspace routes → Interventions: manages repairs (evidence: `reference/workspace-routes.js`)
- Manual registration → Vehicle repository: creates identity (evidence: `reference/workspace/registration-service.js`)
- Manual registration → Owner contacts: records owner (evidence: `reference/workspace/registration-service.js`)
- Manual registration → Audited writes: audits mutation (evidence: `reference/workspace/registration-service.js`)
- Identification routes → Vehicle resolver: resolves vehicle (evidence: `reference/v12-routes.js`)
- Identification routes → Parts catalogue: queries parts (evidence: `reference/v12-routes.js`)
- Identification routes → Workshop service: handles workshop (evidence: `reference/v12-routes.js`)
- Vehicle resolver → Plate normalizer: normalizes plate (evidence: `reference/vehicle/vehicle-resolver.js`)
- Vehicle resolver → Vehicle repository: looks up vehicle (evidence: `reference/vehicle/vehicle-resolver.js`)
- Workshop service → Vehicle repository: uses identity (evidence: `reference/workshop/workshop-vehicle-service.js`)
- Parts catalogue → Local parts: queries catalogue (evidence: `reference/parts/parts-catalog.js`)
- Document service → Document records: stores metadata (evidence: `reference/documents/document-service.js`)
- Document service → Media storage: stores media (evidence: `reference/documents/document-service.js`)
- Document records → PostgreSQL: reads and writes (evidence: `reference/documents/document-repository.js`)
- Vehicle repository → PostgreSQL: reads and writes (evidence: `reference/vehicle/vehicle-repository.js`)
- Vehicle repository → Audited writes: audits changes (evidence: `reference/vehicle/vehicle-repository.js`)
- Local parts → PostgreSQL: queries catalogue (evidence: `reference/parts/local-parts-catalog.js`)
- Local parts → Audited writes: audits changes (evidence: `reference/parts/local-parts-catalog.js`)
- Workspace reads → Vehicle repository: reads records (evidence: `reference/workspace/workspace-repository.js`)
- Workspace reads → PostgreSQL: queries workspace (evidence: `reference/workspace/workspace-repository.js`)
- Owner contacts → PostgreSQL: persists contacts (evidence: `reference/workspace/owner-contacts.js`)
- Interventions → Vehicle repository: uses vehicle (evidence: `reference/workspace/intervention-service.js`)
- Interventions → PostgreSQL: persists repairs (evidence: `reference/workspace/intervention-service.js`)
- Audited writes → PostgreSQL: commits audit (evidence: `reference/writes.js`)
- Audited writes → Media storage: cleans media (evidence: `reference/writes.js`)
- Admin read model → PostgreSQL: queries registry (evidence: `reference/admin/admin-repository.js`)