# anton-kulchytskyi/car-service-book architecture

> Architecture diagram of the GitHub repository anton-kulchytskyi/car-service-book, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anton-kulchytskyi/car-service-book
- Repository: https://github.com/anton-kulchytskyi/car-service-book

## Overview

#### Purpose and Runtime
This is a Next.js App Router application for personal/shared vehicle management: cars, service/expense records, maintenance schedules, ownership transfer, dashboard reporting, profile management, and PDF export. It runs as a TypeScript React server/client application with route handlers under `app/api`, deployable to Vercel per the base README.

#### Route and Layout Composition
Locale-prefixed UI routes partition authenticated application screens from authentication screens. Root and locale layouts establish global and localized shells; `(app)` provides the signed-in area, while `(auth)` isolates login/register. Primary user entry points include:
- `app/[locale]/page.tsx`
- `app/[locale]/(app)/dashboard/page.tsx`
- `app/[locale]/(app)/layout.tsx`
- `app/[locale]/(auth)/login/page.tsx`
- `app/[locale]/layout.tsx`

Internationalization routing/request behavior is centralized in `i18n/routing.ts`, `i18n/request.ts`, and locale dictionaries in `messages/en.json` and `messages/uk.json`.

#### Authentication and Session Boundary
Custom API authentication exposes register, login, logout, and current-user endpoints. JWT/password/session utilities provide the security boundary consumed by protected UI and server logic:
- `app/api/auth/login/route.ts`
- `app/api/auth/register/route.ts`
- `app/api/auth/me/route.ts`
- `lib/auth/jwt.ts`
- `lib/auth/session.ts`
- `proxy.ts`

The expected control flow is browser auth form → API route → password/JWT/session handling → protected localized app routes.

#### Vehicle and Service Domain
Cars are the primary aggregate. Users create, view, edit, delete, transfer, and share/inspect ownership; each car contains maintenance/service records and schedules. UI detail routes model this hierarchy, while REST-style handlers form the mutation/query boundary:
- `app/[locale]/(app)/cars/[id]/page.tsx`
- `app/[locale]/(app)/cars/[id]/records/new/page.tsx`
- `app/api/cars/[id]/route.ts`
- `app/api/cars/[id]/transfer/route.ts`
- `app/api/records/[id]/route.ts`
- `app/api/cars/[id]/schedules/route.ts`

Forms and cards are the main client interaction layer: `components/forms/car-form.tsx`, `components/forms/record-form.tsx`, and `components/cards/car-card.tsx`.

#### Persistence and Domain Automation
Drizzle ORM defines the relational data model and migration history; database access should flow through the DB module rather than route/UI code owning SQL:
- `lib/db/schema.ts`
- `lib/db/index.ts`
- `drizzle.config.ts`
- `drizzle/0005_normal_pixie.sql`

Maintenance synchronization is a distinct domain process, likely reconciling schedule state against car records/mileage:
- `lib/maintenance-sync.ts`
- `app/api/schedules/[scheduleId]/route.ts`
- `components/maintenance-schedules.tsx`

#### Reporting and Document Output
The dashboard aggregates vehicle/service cost information and mileage into visual summaries. PDF export turns car service data into a downloadable report:
- `components/charts/cost-by-type-chart-wrapper.tsx`
- `components/current-mileage.tsx`
- `components/export-pdf-button.tsx`
- `components/pdf/car-service-pdf.tsx`
- `app/[locale]/(app)/dashboard/page.tsx`

#### External Storage and Uploads
Photo/file uploads are mediated by an API route and upload utilities, with Cloudinary as the explicit external media-service integration:
- `app/api/upload/route.ts`
- `lib/cloudinary.ts`
- `lib/upload-files.ts`
- `components/photo-upload.tsx`

This separates browser file selection from cloud-storage credentials and persistent vehicle/record metadata updates.

Main entry points: [`app/[locale]/layout.tsx`](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/layout.tsx) (Locale layout and routes), [`app/[locale]/(app)/layout.tsx`](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(app)/layout.tsx) (Signed-in app shell), [`app/api/cars/[id]/route.ts`](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/api/cars/%5Bid%5D/route.ts) (Vehicle and record API), [`lib/db/index.ts`](https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/db/index.ts) (Drizzle data access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Localized UI"]
  node_locale_shell["Locale layout and routes<br/>route shell<br/>[layout.tsx]"]
  node_i18n["i18n routing<br/>localization<br/>[routing.ts]"]
  node_auth_screens["Login and register<br/>auth screens<br/>[page.tsx]"]
  node_protected_shell["Signed-in app shell<br/>protected layout<br/>[layout.tsx]"]
  node_dashboard["Dashboard reporting<br/>dashboard page<br/>[page.tsx]"]
  node_car_detail["Car and record screens<br/>vehicle UI<br/>[page.tsx]"]
  node_forms_cards["Vehicle interaction components<br/>client components<br/>[car-form.tsx]"]
  node_pdf_export["PDF export<br/>document output"]
  node_photo_upload["Photo upload component<br/>client component<br/>[photo-upload.tsx]"]
end

subgraph group_api["Server APIs"]
  node_auth_api["Authentication API<br/>route handlers<br/>[route.ts]"]
  node_vehicle_api["Vehicle and record API<br/>route handlers<br/>[route.ts]"]
  node_upload_api["Upload API<br/>route handler<br/>[route.ts]"]
end

subgraph group_domain["Domain Services"]
  node_session_guard{{"Session protection<br/>request boundary<br/>[proxy.ts]"}}
  node_auth_service{{"JWT and session service<br/>security service<br/>[session.ts]"}}
  node_database[("Drizzle data access<br/>ORM module<br/>[index.ts]")]
  node_schema[("Relational schema<br/>Drizzle schema<br/>[schema.ts]")]
  node_maintenance["Maintenance synchronization<br/>domain automation"]
end

subgraph group_external["External Services"]
  node_cloudinary[("Cloudinary<br/>media storage")]
end

node_next{{"Next.js App Router<br/>runtime"}}

node_next -->|"serves"| node_locale_shell
node_locale_shell -->|"uses"| node_i18n
node_locale_shell -->|"renders"| node_auth_screens
node_locale_shell -->|"renders"| node_protected_shell
node_session_guard -->|"protects"| node_protected_shell
node_auth_screens -->|"auth requests"| node_auth_api
node_auth_api -->|"authenticates via"| node_auth_service
node_auth_service -->|"establishes session"| node_session_guard
node_protected_shell -->|"contains"| node_dashboard
node_protected_shell -->|"contains"| node_car_detail
node_dashboard -->|"loads aggregates"| node_vehicle_api
node_car_detail -->|"uses"| node_forms_cards
node_forms_cards -->|"queries and mutates"| node_vehicle_api
node_vehicle_api -->|"syncs schedules"| node_maintenance
node_vehicle_api -->|"persists"| node_database
node_maintenance -->|"reads and updates"| node_database
node_database -->|"maps data model"| node_schema
node_dashboard -->|"exports report"| node_pdf_export
node_photo_upload -->|"uploads files"| node_upload_api
node_upload_api -->|"stores media"| node_cloudinary
node_upload_api -->|"updates metadata"| node_database

click node_locale_shell "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/layout.tsx"
click node_i18n "https://github.com/anton-kulchytskyi/car-service-book/blob/main/i18n/routing.ts"
click node_auth_screens "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(auth)/login/page.tsx"
click node_protected_shell "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(app)/layout.tsx"
click node_dashboard "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(app)/dashboard/page.tsx"
click node_car_detail "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(app)/cars/%5Bid%5D/page.tsx"
click node_forms_cards "https://github.com/anton-kulchytskyi/car-service-book/blob/main/components/forms/car-form.tsx"
click node_auth_api "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/api/auth/login/route.ts"
click node_vehicle_api "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/api/cars/%5Bid%5D/route.ts"
click node_upload_api "https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/api/upload/route.ts"
click node_pdf_export "https://github.com/anton-kulchytskyi/car-service-book/blob/main/components/pdf/car-service-pdf.tsx"
click node_session_guard "https://github.com/anton-kulchytskyi/car-service-book/blob/main/proxy.ts"
click node_auth_service "https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/auth/session.ts"
click node_database "https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/db/index.ts"
click node_schema "https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/db/schema.ts"
click node_maintenance "https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/maintenance-sync.ts"
click node_photo_upload "https://github.com/anton-kulchytskyi/car-service-book/blob/main/components/photo-upload.tsx"

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_locale_shell,node_i18n,node_auth_screens,node_protected_shell,node_dashboard,node_car_detail,node_forms_cards,node_pdf_export,node_photo_upload toneBlue
class node_auth_api,node_vehicle_api,node_upload_api toneAmber
class node_session_guard,node_auth_service,node_database,node_schema,node_maintenance toneMint
class node_cloudinary toneRose
class node_next toneNeutral
```

## Components

### Localized UI

Locale-prefixed App Router screens and client components.

- [Locale layout and routes](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/layout.tsx): route shell · Establishes localized application composition. · `app/[locale]/layout.tsx`
- [i18n routing](https://github.com/anton-kulchytskyi/car-service-book/blob/main/i18n/routing.ts): localization · Resolves locale routing and request translations. · `i18n/routing.ts`
- [Login and register](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(auth)/login/page.tsx): auth screens · `app/[locale]/(auth)/login/page.tsx`
- [Signed-in app shell](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(app)/layout.tsx): protected layout · Contains authenticated localized screens. · `app/[locale]/(app)/layout.tsx`
- [Dashboard reporting](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(app)/dashboard/page.tsx): dashboard page · Summarizes vehicle costs and mileage. · `app/[locale]/(app)/dashboard/page.tsx`
- [Car and record screens](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/%5Blocale%5D/(app)/cars/%5Bid%5D/page.tsx): vehicle UI · Vehicle detail and service-record entry hierarchy. · `app/[locale]/(app)/cars/[id]/page.tsx`
- [Vehicle interaction components](https://github.com/anton-kulchytskyi/car-service-book/blob/main/components/forms/car-form.tsx): client components · Car and record forms drive mutations. · `components/forms/car-form.tsx`
- [PDF export](https://github.com/anton-kulchytskyi/car-service-book/blob/main/components/pdf/car-service-pdf.tsx): document output · Builds downloadable car service reports. · `components/pdf/car-service-pdf.tsx`
- [Photo upload component](https://github.com/anton-kulchytskyi/car-service-book/blob/main/components/photo-upload.tsx): client component · Selects files in the browser. · `components/photo-upload.tsx`

### Server APIs

Route handlers provide domain and integration boundaries.

- [Authentication API](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/api/auth/login/route.ts): route handlers · Register, login, logout, and current-user endpoints. · `app/api/auth/login/route.ts`
- [Vehicle and record API](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/api/cars/%5Bid%5D/route.ts): route handlers · Manages cars, transfers, records, and schedules. · `app/api/cars/[id]/route.ts`
- [Upload API](https://github.com/anton-kulchytskyi/car-service-book/blob/main/app/api/upload/route.ts): route handler · Mediates browser file uploads. · `app/api/upload/route.ts`

### Domain Services

Authentication, persistence, and maintenance logic.

- [Session protection](https://github.com/anton-kulchytskyi/car-service-book/blob/main/proxy.ts): request boundary · Protects localized application routes. · `proxy.ts`
- [JWT and session service](https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/auth/session.ts): security service · Handles passwords, JWTs, and sessions. · `lib/auth/session.ts`
- [Drizzle data access](https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/db/index.ts): ORM module · Central relational persistence access. · `lib/db/index.ts`
- [Relational schema](https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/db/schema.ts): Drizzle schema · Defines vehicle, ownership, record, and schedule data. · `lib/db/schema.ts`
- [Maintenance synchronization](https://github.com/anton-kulchytskyi/car-service-book/blob/main/lib/maintenance-sync.ts): domain automation · Reconciles schedule state with records and mileage. · `lib/maintenance-sync.ts`

### External Services

- **Cloudinary**: media storage · External media storage integration.

### Other components

- **Next.js App Router**: runtime · TypeScript React server/client application.

## Connections

- Next.js App Router → Locale layout and routes: serves
- Locale layout and routes → i18n routing: uses
- Locale layout and routes → Login and register: renders
- Locale layout and routes → Signed-in app shell: renders
- Session protection → Signed-in app shell: protects
- Login and register → Authentication API: auth requests
- Authentication API → JWT and session service: authenticates via
- JWT and session service → Session protection: establishes session
- Signed-in app shell → Dashboard reporting: contains
- Signed-in app shell → Car and record screens: contains
- Dashboard reporting → Vehicle and record API: loads aggregates
- Car and record screens → Vehicle interaction components: uses
- Vehicle interaction components → Vehicle and record API: queries and mutates
- Vehicle and record API → Maintenance synchronization: syncs schedules
- Vehicle and record API → Drizzle data access: persists
- Maintenance synchronization → Drizzle data access: reads and updates
- Drizzle data access → Relational schema: maps data model
- Dashboard reporting → PDF export: exports report
- Photo upload component → Upload API: uploads files
- Upload API → Cloudinary: stores media
- Upload API → Drizzle data access: updates metadata