# tharanitharan-m/leettrack architecture

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

- Interactive diagram: https://gitdiagram.com/tharanitharan-m/leettrack
- Repository: https://github.com/tharanitharan-m/leettrack

## Overview

##### Project Type and Purpose
- LeetTrack is a full-stack, server-rendered Next.js application with client-side interactivity, designed as a DSA preparation platform.
- It exposes a React-driven UI, uses Next.js API Routes as its backend, leverages Firebase for auth and data storage, and integrates with an external AI service (Gemini) for code feedback.

##### File Structure Analysis
- Top-level folders:
- public/ – static assets (images, fonts).
- scripts/ – data‐migration and seeding scripts (Node.js/TypeScript).
- src/app/ – Next.js “App Router” pages and API Routes.
– api/feedback/route.ts – server endpoint for sending code to Gemini and storing feedback.
– login/, dashboard/, feedback/[submissionId]/ – page components.
- src/components/ – reusable UI building blocks (common, dashboard, layout, ui).
- src/contexts/ – React Contexts (AuthContext).
- src/lib/ – external service clients and utilities (firebase.ts, utils.ts).
- src/types/ – TypeScript type definitions.
- Configuration files for ESLint, Tailwind (postcss), tsconfig, Next.js, and environment variables indicate typical modern frontend tooling.

##### Key Architectural Points from README
- Client: Next.js with App Router & TailwindCSS.
- Authentication: Firebase Authentication (Google).
- Backend: Next.js API Routes (Node.js serverless functions) running on Vercel.
- Database: Firebase Firestore (NoSQL).
- AI: External Gemini 1.5 Pro API for code analysis.

##### Main Components and Their Interactions
a. User’s Browser (Client)
- Renders Next.js pages (React + SSR/ISR).
- Sends requests to Next.js API routes for data fetching or code submission.
b. Next.js Frontend (src/app, src/components)
- UI pages: Login, Dashboard, Feedback.
- Uses AuthContext to manage user session.
c. Next.js API Layer (src/app/api/feedback/route.ts)
- Verifies Firebase ID tokens.
- Reads/writes Firestore for problem tracking and user progress.
- For code feedback, forwards submissions to Gemini API, processes response, stores feedback.
d. Firebase Services
- Authentication: issues ID tokens on Google Sign-In.
- Firestore: stores users, problem metadata, submission history, streaks.
e. External AI Service (Gemini)
- Receives code and problem context, returns pattern insights and optimization suggestions.
f. Vercel Hosting & CI/CD
- Deploys both frontend and API routes as serverless functions.
g. Local Dev / Scripts
- scripts/seed-problems.ts: populates Firestore with problem data.
- scripts/migrate-problems.ts: transforms or updates existing problem definitions.

##### Architectural Patterns & Design Principles
- Separation of Concerns: clear split between UI components, domain logic (contexts, utils), and data services.
- Serverless Backend: each API Route acts as an independent function, scaling on demand.
- Micro-interactions: small reusable UI primitives in src/components/ui.
- Context-driven State: AuthContext provides user state throughout the app.
- Infrastructure as Code: scripts to automate Firestore seeding/migration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    subgraph "Client Browser"
        Browser["User's Browser"]:::client
    end

    %% Frontend Layer
    subgraph "Next.js Frontend (SSR / Client)" 
        direction TB
        subgraph "Pages" 
            direction TB
            Page_Home["page.tsx"]:::frontend
            Page_Login["login/page.tsx"]:::frontend
            Page_Dashboard["dashboard/page.tsx"]:::frontend
            Page_Feedback["feedback/[submissionId]/page.tsx"]:::frontend
            Layout_App["layout.tsx"]:::frontend
            GlobalsCSS["globals.css"]:::frontend
        end
        subgraph "UI Primitives"
            direction TB
            UI_Button["button.tsx"]:::frontend
            UI_Card["card.tsx"]:::frontend
            UI_Avatar["avatar.tsx"]:::frontend
            UI_Progress["animated-circular-progress-bar.tsx"]:::frontend
        end
        subgraph "Dashboard Components"
            direction TB
            Dash_Table["ProblemsTable.tsx"]:::frontend
            Dash_Stats["DashboardStats.tsx"]:::frontend
            Dash_Progress["ProgressStats.tsx"]:::frontend
            Dash_Filters["FiltersBar.tsx"]:::frontend
            Dash_AddModal["AddProblemModal.tsx"]:::frontend
            Dash_SubmitModal["SubmitModal.tsx"]:::frontend
        end
        subgraph "Common & Layout Components"
            direction TB
            Common_CodeBlock["CodeBlock.tsx"]:::frontend
            Common_Layout["Layout.tsx"]:::frontend
            Common_Navbar["Navbar.tsx"]:::frontend
        end
        AuthContext["AuthContext.tsx"]:::frontend
        subgraph "Library"
            direction TB
            Lib_Firebase["firebase.ts"]:::frontend
            Lib_Utils["utils.ts"]:::frontend
        end
        subgraph "Type Definitions"
            direction TB
            Types_Index["index.ts"]:::frontend
            Types_User["user.ts"]:::frontend
        end
    end

    %% API Layer
    subgraph "Next.js API Layer (Serverless)" 
        direction TB
        API_Feedback["api/feedback/route.ts"]:::backend
    end

    %% Services
    subgraph "Managed Services"
        direction TB
        Firebase_Auth["Firebase Auth"]:::service
        Firestore["Firebase Firestore"]:::service
        Gemini["Gemini AI API"]:::service
    end

    %% Infrastructure
    Vercel["Vercel Hosting & CI/CD"]:::infra

    %% Scripts
    subgraph "Dev Scripts"
        direction TB
        Seed["scripts/seed-problems.ts"]:::scripts
        Migrate["scripts/migrate-problems.ts"]:::scripts
    end

    %% Public Assets
    Public["public/"]:::assets

    %% Config
    subgraph "Configuration & Tooling"
        nextConfig["next.config.js"]:::infra
        tsconfig["tsconfig.json"]:::infra
        eslint[".eslintrc.json"]:::infra
        postcss["postcss.config.mjs"]:::infra
        packageJson["package.json"]:::infra
    end

    %% Connections
    Browser -->|SSR/CSR Requests| Page_Home
    Browser -->|Navigates| Page_Login
    Browser -->|Navigates| Page_Dashboard
    Browser -->|Navigates| Page_Feedback

    Browser -->|AJAX/Fetch| API_Feedback
    API_Feedback -->|Verify ID Token| Firebase_Auth
    API_Feedback -->|Read/Write| Firestore
    API_Feedback -->|HTTPS Request| Gemini

    AuthContext -->|Provides Token| Browser
    Lib_Firebase -->|SDK| Firebase_Auth
    Lib_Firebase -->|SDK| Firestore

    Seed -->|Populate| Firestore
    Migrate -->|Transform| Firestore

    allFrontends([Pages & Components]) -->|Deploy| Vercel
    API_Feedback -->|Deploy| Vercel

    Public -->|Served By| Vercel
    nextConfig -->|Configures| Vercel

    %% Click Events
    click Page_Home "https://github.com/tharanitharan-m/leettrack/blob/main/src/app/page.tsx"
    click Page_Login "https://github.com/tharanitharan-m/leettrack/blob/main/src/app/login/page.tsx"
    click Page_Dashboard "https://github.com/tharanitharan-m/leettrack/blob/main/src/app/dashboard/page.tsx"
    click Page_Feedback "https://github.com/tharanitharan-m/leettrack/blob/main/src/app/feedback/[submissionId]/page.tsx"
    click Layout_App "https://github.com/tharanitharan-m/leettrack/blob/main/src/app/layout.tsx"
    click GlobalsCSS "https://github.com/tharanitharan-m/leettrack/blob/main/src/app/globals.css"

    click UI_Button "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/ui/button.tsx"
    click UI_Card "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/ui/card.tsx"
    click UI_Avatar "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/ui/avatar.tsx"
    click UI_Progress "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/ui/animated-circular-progress-bar.tsx"

    click Dash_Table "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/dashboard/ProblemsTable.tsx"
    click Dash_Stats "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/dashboard/DashboardStats.tsx"
    click Dash_Progress "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/dashboard/ProgressStats.tsx"
    click Dash_Filters "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/dashboard/FiltersBar.tsx"
    click Dash_AddModal "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/dashboard/AddProblemModal.tsx"
    click Dash_SubmitModal "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/dashboard/SubmitModal.tsx"

    click Common_CodeBlock "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/common/CodeBlock.tsx"
    click Common_Layout "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/layout/Layout.tsx"
    click Common_Navbar "https://github.com/tharanitharan-m/leettrack/blob/main/src/components/layout/Navbar.tsx"

    click AuthContext "https://github.com/tharanitharan-m/leettrack/blob/main/src/contexts/AuthContext.tsx"

    click API_Feedback "https://github.com/tharanitharan-m/leettrack/blob/main/src/app/api/feedback/route.ts"

    click Lib_Firebase "https://github.com/tharanitharan-m/leettrack/blob/main/src/lib/firebase.ts"
    click Lib_Utils "https://github.com/tharanitharan-m/leettrack/blob/main/src/lib/utils.ts"

    click Types_Index "https://github.com/tharanitharan-m/leettrack/blob/main/src/types/index.ts"
    click Types_User "https://github.com/tharanitharan-m/leettrack/blob/main/src/types/user.ts"

    click Seed "https://github.com/tharanitharan-m/leettrack/blob/main/scripts/seed-problems.ts"
    click Migrate "https://github.com/tharanitharan-m/leettrack/blob/main/scripts/migrate-problems.ts"

    click Public "https://github.com/tharanitharan-m/leettrack/tree/main/public/"

    click nextConfig "https://github.com/tharanitharan-m/leettrack/blob/main/next.config.js"
    click tsconfig "https://github.com/tharanitharan-m/leettrack/blob/main/tsconfig.json"
    click eslint "https://github.com/tharanitharan-m/leettrack/blob/main/.eslintrc.json"
    click postcss "https://github.com/tharanitharan-m/leettrack/blob/main/postcss.config.mjs"
    click packageJson "https://github.com/tharanitharan-m/leettrack/blob/main/package.json"

    %% Styles
    classDef client fill:#eef,stroke:#88b,stroke-width:2px;
    classDef frontend fill:#ddf,stroke:#339,stroke-width:2px;
    classDef backend fill:#dfd,stroke:#393,stroke-width:2px;
    classDef service fill:#fed,stroke:#fa0,stroke-width:2px;
    classDef infra fill:#eee,stroke:#999,stroke-width:2px;
    classDef scripts fill:#fdf,stroke:#c39,stroke-width:2px;
    classDef assets fill:#efe,stroke:#3a3,stroke-width:2px;
```
