# pcdaco/pcdaco-web architecture

> Architecture diagram of the GitHub repository pcdaco/pcdaco-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pcdaco/pcdaco-web
- Repository: https://github.com/pcdaco/pcdaco-web

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (App Router), React, and TypeScript.
- It provides role-based dashboards (admin, consultant, technician, user) to manage cars, bookings, inspections, reports, and withdrawals.
- It integrates with Firebase (auth and possibly data storage) and uses server-side rendering (SSR) and server actions.

##### File structure
- **app/**: Next.js entry points, nested layouts, routes under (auth), (dashboard)/(admin|consultants|technicians). Contains React Server Components, Client Components, and server actions.
- **components/**: Reusable UI pieces (tables, forms, dialogs, data-table, ui primitives).
- **domains/** & **constants/**: Domain-driven design—Zod schemas, TypeScript models, enums, response types.
- **hooks/**: Encapsulate data-fetching and form logic (React Query or custom hooks).
- **lib/**: Utility functions, axios.server.ts for server-side API calls, SignalR integration for real-time updates.
- **stores/**: Global client-state (e.g., url params, Zustand or Context providers).
- **configs/**: Third-party config (Firebase).
- Top-level config and deployment: Dockerfile, .github workflows (CI/CD), next.config.ts, middleware.ts (auth guard).

##### Key insights from README
- Uses Next.js App Router for SSR/SSG, built-in routing and API support.
- Firebase configured via environment variables for auth/data.
- Deployed on Vercel or Docker container.

##### Main components and their relationships
A. **Client (Browser)**
- Renders React Client Components (tables, forms, modals).
- Initiates navigation between pages under `/auth` and `/dashboard`.
- Uses hooks to communicate with the Next.js server via fetch or form submissions (server actions).

B. **Next.js Application Server**
- **App Router**: handles routing, nested layouts, SSR (Server Components) and CSR (Client Components).
- **Server Actions**: API endpoints invoked from Client Components via form submissions or fetch calls.
- **axios.server.ts**: encapsulates HTTP calls to back-end services or directly to Firebase REST endpoints.
- **SignalR Location Hub**: for real-time location updates via WebSockets.

C. **Business Logic & Domain Layer**
- **domains/** & **constants/**: validation schemas, model definitions, enums—shared between server and client components.
- **hooks/**: data-fetching, caching strategies, and form handling logic (likely backed by React Query or built-in fetch caching).

D. **Data Sources & External Services**
- **Firebase**: authentication, possibly Firestore/Realtime Database or Storage.
- **External REST APIs**: any internal microservices if axios.server.ts points to them.
- **SignalR Hub**: real-time location service.

E. **Deployment & DevOps**
- **Docker**: containerizes the Next.js app.
- **GitHub Actions**: CI pipeline (docker-image.yml).
- **Vercel (optional)**: automatic deployments.

##### Architectural patterns and design principles
- **Monolithic full-stack** but layered: Presentation (React), Application (Next.js), Domain (schemas/models), Infrastructure (utils, axios, SignalR).
- **Server-side rendering** mixed with **client-side** interactivity.
- **Domain-driven design**: clear separation of schemas, models, and business rules.
- **Component-based UI** with consistent design system (components/ui).
- **Hooks** abstract data access and form logic.
- **Server Actions** for secure form submissions and mutations.

##### Essential elements
- **Clear component labels** (e.g., “Next.js App Router”, “Server Component: app/dashboard/layout.tsx”, “Hook: use-car.ts”).
- **Annotations** for critical files (e.g., middleware.ts guards routes, axios.server.ts abstracts HTTP calls).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Client Layer
    subgraph "Browser Client"
        direction TB
        Client("React Client Components"):::ui
        Hooks("Hooks (hooks/)"):::business
        Stores("Stores (stores/)"):::business
    end

    %% Next.js Server Layer
    subgraph "Next.js Server"
        direction TB
        NextRouter("Next.js App Router (app/)"):::server
        GlobalLayout("Global Layout & Error Handling\n(app/layout.tsx, app/error.tsx, app/not-found.tsx)"):::server
        DashboardLayout("Shared Dashboard Layout\n(app/(dashboard)/layout.tsx)"):::server
        AuthRoutes("Auth Routes & Server Actions\n(app/(auth)/login/page.tsx, action.ts)"):::server
        AdminRoutes("Admin Dashboard Routes\n(app/(dashboard)/(admin)/)"):::server
        ConsultantRoutes("Consultants Dashboard Routes\n(app/(dashboard)/(consultants)/)"):::server
        TechRoutes("Technicians Dashboard Routes\n(app/(dashboard)/(technicians)/)"):::server
        Actions("Server Actions\n(app/actions/)"):::server
        Axios("Axios HTTP Client\n(app/axios.server.ts)"):::server
        Middleware("Middleware Auth Guard\n(middleware.ts)"):::server
    end

    %% Domain & Business Logic Layer
    subgraph "Domain & Business Logic"
        direction TB
        Schemas("Domain Schemas & Validation\n(domains/schemas/)"):::business
        StoreTypes("Query Keys & Types\n(domains/stores/query-key.d.ts)"):::business
        ConstModels("Constants Models\n(constants/models/)"):::business
        ConstEnums("Constants Enums\n(constants/enums/)"):::business
        ConstResponses("Constants Responses\n(constants/responses/)"):::business
    end

    %% Data Sources & External Services Layer
    subgraph "Data Sources & External Services"
        direction TB
        Firebase("Firebase Service\n(configs/firebase.config.ts)"):::external
        SignalR("SignalR Location Hub\n(lib/signalr/location-hub.ts)"):::external
        ExternalAPIs("External REST APIs"):::external
    end

    %% DevOps & Deployment Layer
    subgraph "DevOps & Deployment"
        direction TB
        Docker("Dockerfile"):::devops
        CI("CI/CD Workflow\n(.github/workflows/docker-image.yml)"):::devops
        NextConfig("Next.js Config\n(next.config.ts)"):::devops
    end

    %% Connections
    Client -->|navigates| NextRouter
    Client -->|uses| Hooks
    Client -->|reads| Stores
    Hooks -->|calls| NextRouter
    NextRouter -->|serves| GlobalLayout
    GlobalLayout -->|wraps| DashboardLayout
    NextRouter -->|routes to| AuthRoutes
    DashboardLayout -->|renders| AdminRoutes
    DashboardLayout -->|renders| ConsultantRoutes
    DashboardLayout -->|renders| TechRoutes
    NextRouter -->|invokes| Actions
    NextRouter -->|uses| Axios
    NextRouter -->|protected by| Middleware
    Actions -->|validates via| Schemas
    Actions -->|uses| StoreTypes
    Actions -->|references| ConstModels
    Actions -->|references| ConstEnums
    Actions -->|references| ConstResponses
    Axios -->|calls| Firebase
    Axios -->|calls| ExternalAPIs
    Actions -->|connects| SignalR
    SignalR <-->|real-time| Client
    Docker -->|builds| NextRouter
    CI -->|deploys| NextRouter
    NextConfig -->|configures| NextRouter

    %% Click Events
    click NextRouter "https://github.com/pcdaco/pcdaco-web/tree/main/app/"
    click AuthRoutes "https://github.com/pcdaco/pcdaco-web/blob/main/app/(auth)/login/page.tsx"
    click AuthRoutes "https://github.com/pcdaco/pcdaco-web/blob/main/app/(auth)/login/action.ts"
    click AdminRoutes "https://github.com/pcdaco/pcdaco-web/tree/main/app/(dashboard)/(admin)/"
    click ConsultantRoutes "https://github.com/pcdaco/pcdaco-web/tree/main/app/(dashboard)/(consultants)/"
    click TechRoutes "https://github.com/pcdaco/pcdaco-web/tree/main/app/(dashboard)/(technicians)/"
    click DashboardLayout "https://github.com/pcdaco/pcdaco-web/blob/main/app/(dashboard)/layout.tsx"
    click GlobalLayout "https://github.com/pcdaco/pcdaco-web/blob/main/app/layout.tsx"
    click GlobalLayout "https://github.com/pcdaco/pcdaco-web/blob/main/app/error.tsx"
    click GlobalLayout "https://github.com/pcdaco/pcdaco-web/blob/main/app/not-found.tsx"
    click Actions "https://github.com/pcdaco/pcdaco-web/tree/main/app/actions/"
    click Axios "https://github.com/pcdaco/pcdaco-web/blob/main/app/axios.server.ts"
    click SignalR "https://github.com/pcdaco/pcdaco-web/blob/main/lib/signalr/location-hub.ts"
    click Schemas "https://github.com/pcdaco/pcdaco-web/tree/main/domains/schemas/"
    click StoreTypes "https://github.com/pcdaco/pcdaco-web/blob/main/domains/stores/query-key.d.ts"
    click ConstModels "https://github.com/pcdaco/pcdaco-web/tree/main/constants/models/"
    click ConstEnums "https://github.com/pcdaco/pcdaco-web/tree/main/constants/enums/"
    click ConstResponses "https://github.com/pcdaco/pcdaco-web/tree/main/constants/responses/"
    click Hooks "https://github.com/pcdaco/pcdaco-web/tree/main/hooks/"
    click Firebase "https://github.com/pcdaco/pcdaco-web/blob/main/configs/firebase.config.ts"
    click Middleware "https://github.com/pcdaco/pcdaco-web/blob/main/middleware.ts"
    click Docker "https://github.com/pcdaco/pcdaco-web/tree/main/Dockerfile"
    click CI "https://github.com/pcdaco/pcdaco-web/blob/main/.github/workflows/docker-image.yml"
    click NextConfig "https://github.com/pcdaco/pcdaco-web/blob/main/next.config.ts"
    click Stores "https://github.com/pcdaco/pcdaco-web/blob/main/stores/store.ts"
    click Stores "https://github.com/pcdaco/pcdaco-web/blob/main/stores/use-params.ts"
    click Client "https://github.com/pcdaco/pcdaco-web/tree/main/components/ui/"
    click Client "https://github.com/pcdaco/pcdaco-web/tree/main/components/"

    %% Styles
    classDef ui fill:#e0f7e9,stroke:#27ae60,color:#145a32;
    classDef server fill:#eaf2fc,stroke:#21618c,color:#1b2631;
    classDef business fill:#fef9e7,stroke:#f39c12,color:#7e5109;
    classDef external fill:#fbeee6,stroke:#d35400,color:#78281f;
    classDef devops fill:#f4f6f7,stroke:#7b7d7d,color:#2c3e50;
```
