# piyush-eon/ai-car-marketplace architecture

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

- Interactive diagram: https://gitdiagram.com/piyush-eon/ai-car-marketplace
- Repository: https://github.com/piyush-eon/ai-car-marketplace

## Overview

##### Main Components
- Frontend (Client/UI)
- The entire UI is built in the Next.js app directory. Notice how the UI is broken into separate route groups (admin, auth, main) each handling different user flows:
▪ “(admin)” for administration tasks (managing cars, settings, dashboards, test drives).
▪ “(auth)” for authentication flows (sign-in and sign-up).
▪ “(main)” for the customer front-end (cars display, reservations, saved cars, test drive requests, and waitlist).
- Shared UI components in the “components” folder (e.g., car-card, header, home-search, test-drive-card) along with a UI kit under “components/ui” that leverages Shadcn UI.

- Server/Backend Actions
- The “actions” folder segments contain server actions related to various aspects such as admin, car listings, test drives, and settings. These likely serve as API endpoints or server-side logic triggered by Next.js server actions.
- The “middleware.js” file which may handle request validation, authentication checks, or redirects.

- Data Layer:
- The “prisma” directory holds all database schema definitions and migrations, ensuring that the ORM (Prisma) manages data structure and interactions.
- The “lib” folder includes modules for interacting with Supabase (“supabase.js”), Prisma (“prisma.js”), and other helpers (e.g., “data.js”, “checkUser.js”, “arcjet.js”).

- External Services:
- Authentication via Clerk is indicated by the environment variables (e.g., NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY) and the routes in the “(auth)” segment.
- ArcJet and Gemini API are external integrations whose keys are needed in the .env file.

##### Relationships and Interactions
- The Client (UI) interacts with the Server layer:
- When a user (admin or customer) interacts with the site, Next.js renders pages from the “app” segment.
- Server-side actions from the “actions” folder are called to fetch or mutate data.
- The Server layer communicates with the Data Layer:
- This interaction is managed by Prisma and Supabase through helper libraries (found in “lib”) to perform CRUD operations.
- External Connections:
- Authentication flows interact with Clerk.
- Integration with external APIs like ArcJet and Gemini occurs as needed through calls likely wrapped in the “lib” or “actions” modules.

##### Architectural Patterns and Design Principles
- Next.js with the new app directory promotes server-side rendering and server components where necessary.
- Clear separation between front-end route segments (admin vs. main vs. auth) indicates a domain-driven design.
- Use of “actions” for encapsulated server logic ensures clean separation between client and server responsibilities.
- Adherence to modularity: the usage of dedicated component, hooks, and helper libraries keeps concerns separated.
- Use of configuration and external environment variables emphasizes a twelve-factor app approach.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend Layer
    subgraph "Frontend"
        subgraph "UI Routes"
            AdminUI["Admin UI (app/(admin)/admin)"]
            AuthUI["Auth UI (app/(auth))"]
            MainUI["Main UI (app/(main))"]
        end
        subgraph "Shared UI Components"
            CarCard["Car Card"]
            Header["Header"]
            HomeSearch["Home Search"]
            TestDriveCard["Test Drive Card"]
            UIKit["UI Kit"]
        end
    end

    %% Backend Server Actions
    subgraph "Backend Actions"
        AdminActions["Admin Actions"]
        CarsListing["Car Listing Actions"]
        CarsActions["Car Actions"]
        HomeActions["Home Actions"]
        SettingsActions["Settings"]
        TestDriveActions["Test Drive Actions"]
        Middleware["Middleware"]
    end

    %% Data Layer
    subgraph "Data Layer"
        Prisma["Prisma ORM"]
        Lib["Lib & Helpers"]
    end

    %% External Services
    subgraph "External Services"
        Clerk["Clerk Authentication"]
        ArcJet["ArcJet API"]
        Gemini["Gemini API"]
    end

    %% Connections from Frontend to Backend
    AdminUI -->|"manages"| AdminActions
    MainUI -->|"handles_listings"| CarsListing
    MainUI -->|"handles_cars"| CarsActions
    MainUI -->|"handles_home"| HomeActions
    MainUI -->|"handles_testdrives"| TestDriveActions
    AdminUI -->|"updates_settings"| SettingsActions
    AuthUI -->|"triggers_auth"| Middleware

    %% Middleware to External Authentication
    Middleware -->|"auth_validates"| Clerk

    %% Backend Actions to Data Layer via Lib
    AdminActions -->|"db_calls"| Lib
    CarsListing -->|"db_calls"| Lib
    CarsActions -->|"db_calls"| Lib
    HomeActions -->|"db_calls"| Lib
    SettingsActions -->|"db_calls"| Lib
    TestDriveActions -->|"db_calls"| Lib

    %% Lib interacts with Prisma and External APIs
    Lib -->|"orm_operations"| Prisma
    Lib -->|"calls_arcjet"| ArcJet
    Lib -->|"calls_gemini"| Gemini

    %% Styles
    classDef frontend fill:#CCF,stroke:#003366,stroke-width:2px;
    classDef backend fill:#CFC,stroke:#006600,stroke-width:2px;
    classDef data fill:#FFC,stroke:#996600,stroke-width:2px;
    classDef external fill:#FCC,stroke:#990000,stroke-width:2px;

    %% Class Assignments
    class AdminUI,AuthUI,MainUI,CarCard,Header,HomeSearch,TestDriveCard,UIKit frontend;
    class AdminActions,CarsListing,CarsActions,HomeActions,SettingsActions,TestDriveActions,Middleware backend;
    class Prisma,Lib data;
    class Clerk,ArcJet,Gemini external;

    %% Click Events for Frontend
    click AdminUI "https://github.com/piyush-eon/ai-car-marketplace/tree/main/app/(admin)/admin/"
    click AuthUI "https://github.com/piyush-eon/ai-car-marketplace/tree/main/app/(auth)/"
    click MainUI "https://github.com/piyush-eon/ai-car-marketplace/tree/main/app/(main)/"
    click CarCard "https://github.com/piyush-eon/ai-car-marketplace/blob/main/components/car-card.jsx"
    click Header "https://github.com/piyush-eon/ai-car-marketplace/blob/main/components/header.jsx"
    click HomeSearch "https://github.com/piyush-eon/ai-car-marketplace/blob/main/components/home-search.jsx"
    click TestDriveCard "https://github.com/piyush-eon/ai-car-marketplace/blob/main/components/test-drive-card.jsx"
    click UIKit "https://github.com/piyush-eon/ai-car-marketplace/tree/main/components/ui/"

    %% Click Events for Backend Actions
    click AdminActions "https://github.com/piyush-eon/ai-car-marketplace/blob/main/actions/admin.js"
    click CarsListing "https://github.com/piyush-eon/ai-car-marketplace/blob/main/actions/car-listing.js"
    click CarsActions "https://github.com/piyush-eon/ai-car-marketplace/blob/main/actions/cars.js"
    click HomeActions "https://github.com/piyush-eon/ai-car-marketplace/blob/main/actions/home.js"
    click SettingsActions "https://github.com/piyush-eon/ai-car-marketplace/blob/main/actions/settings.js"
    click TestDriveActions "https://github.com/piyush-eon/ai-car-marketplace/blob/main/actions/test-drive.js"
    click Middleware "https://github.com/piyush-eon/ai-car-marketplace/blob/main/middleware.js"

    %% Click Events for Data Layer
    click Prisma "https://github.com/piyush-eon/ai-car-marketplace/tree/main/prisma/"
    click Lib "https://github.com/piyush-eon/ai-car-marketplace/tree/main/lib/"

    %% Click Event for External API Integration
    click ArcJet "https://github.com/piyush-eon/ai-car-marketplace/blob/main/lib/arcjet.js"
```
