# aidankhatana/zoltai architecture

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

- Interactive diagram: https://gitdiagram.com/aidankhatana/zoltai
- Repository: https://github.com/aidankhatana/zoltai

## Overview

##### Main Components
- Frontend (Presentation Layer):
- Represented by Next.js pages (e.g., pages in src/app such as “about”, “login”, “register”, “profile”, “quizzes”, “roadmaps”, etc.).
- Contains reusable UI components (e.g., Header, Footer, Navbar, Hero, CTA) found in the src/components directory.
- Provides layouts and context providers (e.g., AuthContext, RoadmapContext) that manage client-side state.

- API / Backend Services:
- The project exposes a series of API endpoints under src/app/api that handle authentication (login, register), quiz retrieval, roadmap queries, environment and database checks, and more.
- Each endpoint is defined as a route (using Next.js API Routes) corresponding to specific functionalities.

- Business Logic and Libraries:
- Core functionalities such as authentication and utility functions are encapsulated in the src/lib directory.
- Specifically, integration with the Gemini API is managed through modules in src/lib/gemini and src/lib/gemini/index.ts.
- The src/lib/db directory (with pg-client.ts) indicates that a PostgreSQL database is likely used.

- External Services:
- Integration with the Google Gemini API for AI-powered learning path generation.
- Authentication likely relies on a third-party or in-built NextAuth.js driver.
- Deployment is on Vercel, and deployment-related files (e.g., vercel.json) should be noted.

##### Relationships and Interactions
- User Interaction Flow:
- Users load the Next.js frontend (served on Vercel) and navigate through pages such as login, registration, quizzes, and learning roadmap displays.
- Contexts (AuthContext and RoadmapContext) ensure that user-specific data and application state are passed down the component tree.

- API Communication:
- Frontend components communicate with the backend through RESTful API endpoints (e.g., under /api/auth, /api/quizzes, /api/roadmaps).

- Backend Processing:
- The API endpoints invoke functions in the lib directory. For example, authentication endpoints use functions from src/lib/auth.ts.
- API endpoints manage database interaction through the pg-client in src/lib/db.
- The Gemini API integrations are performed at the business logic layer (src/lib/gemini), with endpoints calling these functions to process user queries and generate personalized learning paths.

- External Service Integration:
- NextAuth.js (if detailed further in code/config) as a component handling authentication flows.

##### Architectural Patterns and Design Principles
- Modular Separation:
- The project shows clear separation between presentation (pages and UI components), business logic (lib functions for authentication, Gemini integration, and utility operations), and API endpoints that act as intermediaries.

- API-First Approach:
- The clear definition of API subdirectories (e.g., for authentication, quizzes, roadmaps) suggests that the system is designed around a robust and modular API layer.

- Use of Context Providers:
- Application-wide state is managed via React Context (AuthContext and RoadmapContext), which is important for user authentication and roadmap state.

- Serverless/Route-Based Functions:
- By using Next.js API routes, the application follows a serverless or microservice-inspired pattern where each API endpoint encapsulates a specific piece of functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User Browser"):::external

    subgraph "Frontend (Next.js & React)"
        F1("About Page"):::frontend
        F2("Login Page"):::frontend
        F3("Register Page"):::frontend
        F4("Profile Page"):::frontend
        F5("Quiz Page"):::frontend
        F6("Roadmap Generator Page"):::frontend
        F7("Roadmap Details Page"):::frontend
        F8("Other Roadmaps"):::frontend

        U1("Header"):::ui
        U2("Footer"):::ui
        U3("Navbar"):::ui
        U4("Hero"):::ui
        U5("CTA"):::ui
        U6("Features"):::ui
        U7("Learning Roadmap"):::ui
        U8("Skill Level Assessment"):::ui
        U9("Theme Toggle"):::ui
        U10("UI Components Set"):::ui

        CP1("Auth Context"):::context
        CP2("Roadmap Context"):::context
    end

    subgraph "API Endpoints"
        API1("Auth Login API"):::api
        API2("Auth Register API"):::api
        API3("Quizzes API"):::api
        API4("Roadmaps API"):::api
        API5("Roadmap Details API"):::api
        API6("DB Check API"):::api
        API7("Env Check API"):::api
        API8("PG Test API"):::api
        API9("Public DB Test API"):::api
        API10("Test DB API"):::api
        API11("User Progress API"):::api
    end

    subgraph "Business Logic & Libraries"
        BL1("Auth Module"):::logic
        BL2("Utility Functions"):::logic
        BL3("Types Definition"):::logic
        BL4("Database Integration"):::logic
        BL5("Gemini Integration"):::logic
    end

    subgraph "External Services & Config"
        EX1("Google Gemini API"):::external
        EX2("NextAuth.js Service"):::external
        EX3("PostgreSQL Database"):::external
        EX4("Next Config"):::config
        EX5("Vercel Config"):::config
        EX6("Tailwind Config"):::config
        EX7("TypeScript Config"):::config
    end

    %% Data Flow: User loads Frontend Pages
    A -->|"loads"| F1
    A --> F2
    A --> F3
    A --> F4
    A --> F5
    A --> F6
    A --> F7
    A --> F8

    %% Frontend internal interactions
    F1 --> U1
    F2 --> U2
    F3 --> U3
    F4 --> U4
    F5 --> U5
    F6 --> U6
    F7 --> U7
    F8 --> U8
    U1 --> CP1
    U2 --> CP2

    %% Frontend calling API Endpoints
    F2 -->|"calls"| API1
    F3 -->|"calls"| API2
    F5 -->|"calls"| API3
    F6 -->|"calls"| API4
    F7 -->|"calls"| API5
    F4 -->|"calls"| API11

    %% API Endpoints triggering Business Logic
    API1 -->|"executes"| BL1
    API2 -->|"executes"| BL1
    API3 -->|"executes"| BL2
    API4 -->|"executes"| BL5
    API5 -->|"executes"| BL5
    API6 -->|"executes"| BL4
    API7 -->|"executes"| BL4
    API8 -->|"executes"| BL4
    API9 -->|"executes"| BL4
    API10 -->|"executes"| BL4
    API11 -->|"executes"| BL2

    %% Business Logic interacting with External Services
    BL5 -->|"integrates"| EX1
    BL1 -->|"utilizes"| EX2
    BL4 -->|"queries"| EX3

    %% Config relation (deployment/build context)
    F1 --- EX4
    F2 --- EX4
    F3 --- EX4
    API1 --- EX5
    API2 --- EX5
    API3 --- EX5
    BL1 --- EX6
    BL2 --- EX7

    %% Click Events - Frontend Pages
    click F1 "https://github.com/aidankhatana/zoltai/blob/main/src/app/about/page.tsx"
    click F2 "https://github.com/aidankhatana/zoltai/blob/main/src/app/login/page.tsx"
    click F3 "https://github.com/aidankhatana/zoltai/blob/main/src/app/register/page.tsx"
    click F4 "https://github.com/aidankhatana/zoltai/blob/main/src/app/profile/page.tsx"
    click F5 "https://github.com/aidankhatana/zoltai/blob/main/src/app/quizzes/[id]/page.tsx"
    click F6 "https://github.com/aidankhatana/zoltai/blob/main/src/app/roadmap-generator/page.tsx"
    click F7 "https://github.com/aidankhatana/zoltai/blob/main/src/app/roadmaps/[id]/page.tsx"
    click F8 "https://github.com/aidankhatana/zoltai/tree/main/src/app/roadmaps"

    %% Click Events - UI Components
    click U1 "https://github.com/aidankhatana/zoltai/blob/main/src/components/Header.tsx"
    click U2 "https://github.com/aidankhatana/zoltai/blob/main/src/components/Footer.tsx"
    click U3 "https://github.com/aidankhatana/zoltai/blob/main/src/components/Navbar.tsx"
    click U4 "https://github.com/aidankhatana/zoltai/blob/main/src/components/Hero.tsx"
    click U5 "https://github.com/aidankhatana/zoltai/blob/main/src/components/CTA.tsx"
    click U6 "https://github.com/aidankhatana/zoltai/blob/main/src/components/Features.tsx"
    click U7 "https://github.com/aidankhatana/zoltai/blob/main/src/components/LearningRoadmap.tsx"
    click U8 "https://github.com/aidankhatana/zoltai/blob/main/src/components/SkillLevelAssessment.tsx"
    click U9 "https://github.com/aidankhatana/zoltai/blob/main/src/components/ThemeToggle.tsx"
    click U10 "https://github.com/aidankhatana/zoltai/tree/main/src/components/ui"

    %% Click Events - API Endpoints
    click API1 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/auth/login/route.ts"
    click API2 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/auth/register/route.ts"
    click API3 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/quizzes/[id]/route.ts"
    click API4 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/roadmaps/route.ts"
    click API5 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/roadmaps/[id]/route.ts"
    click API6 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/check-db/route.ts"
    click API7 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/env-check/route.ts"
    click API8 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/pg-test/route.ts"
    click API9 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/public-db-test/route.ts"
    click API10 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/test-db/route.ts"
    click API11 "https://github.com/aidankhatana/zoltai/blob/main/src/app/api/users/progress/route.ts"

    %% Click Events - Business Logic & Libraries
    click BL1 "https://github.com/aidankhatana/zoltai/blob/main/src/lib/auth.ts"
    click BL2 "https://github.com/aidankhatana/zoltai/blob/main/src/lib/utils.ts"
    click BL3 "https://github.com/aidankhatana/zoltai/blob/main/src/lib/types.ts"
    click BL4 "https://github.com/aidankhatana/zoltai/blob/main/src/lib/db/pg-client.ts"
    click BL5 "https://github.com/aidankhatana/zoltai/blob/main/src/lib/gemini.ts"

    %% Click Events - Context Providers
    click CP1 "https://github.com/aidankhatana/zoltai/blob/main/src/contexts/AuthContext.tsx"
    click CP2 "https://github.com/aidankhatana/zoltai/blob/main/src/contexts/RoadmapContext.tsx"

    %% Click Events - External Config Files
    click EX4 "https://github.com/aidankhatana/zoltai/blob/main/next.config.js"
    click EX5 "https://github.com/aidankhatana/zoltai/blob/main/vercel.json"
    click EX6 "https://github.com/aidankhatana/zoltai/blob/main/tailwind.config.js"
    click EX7 "https://github.com/aidankhatana/zoltai/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef ui fill:#B0E0E6,stroke:#000,stroke-width:1px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef logic fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef context fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef config fill:#F5DEB3,stroke:#000,stroke-width:1px;
```
