# snsa-kscc/edureteai architecture

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

- Interactive diagram: https://gitdiagram.com/snsa-kscc/edureteai
- Repository: https://github.com/snsa-kscc/edureteai

## Overview

##### Project Type and Purpose
- edureteAI is a full-stack, chat-focused web application built with Next.js (App Router) that leverages large language models (LLMs) to let students experiment with and compare AI model outputs.
- It integrates user management (Clerk), payment/billing (Stripe + Neon PostgreSQL), chat memory (Upstash Redis), multimodal uploads, and streams UI components via Vercel’s AI SDK.

##### High-Level File/Folder Structure Analysis
- app/ → Next.js App Router: React Server/Client components, page layouts, and REST/edge API route handlers (chat, billing, uploads).
- components/ & components/ui/ → Reusable UI building blocks (chat form, sidebar, design system).
- lib/ → Business logic & integrations (chat config, model limits, Stripe actions, Redis/Neon actions).
- db/ & migrations/ → Database schema definitions and SQL migrations for PostgreSQL.
- hooks/ → Custom React hooks (clipboard, streaming text, image uploads).
- public/ → Static assets (CSS, JS, fonts, images).
- middleware.ts, next.config.mjs, vercel.json → Deployment and routing configurations.

##### Additional README Insights
- “Generative UI architecture”: UI components stream in real-time based on AI responses.
- External services: Clerk for authentication, Upstash Redis for KV chat memory, Neon PostgreSQL for billing/rate-limit, Stripe for payments, Vercel AI SDK + third-party LLM providers.

a. Main Components
- User Browser (React Client)
- Next.js Server (Server-Side & Edge Functions)
- API Routes Layer (chat, stripe, upload-picture, send-report)
- Authentication Service (Clerk)
- AI Orchestration (Vercel AI SDK + multiple LLM Vendors)
- KV Store (Upstash Redis)
- Relational DB (Neon PostgreSQL)
- Payment Processor (Stripe)
- Object Storage or Upload Service (for image uploads)
b. Relationships & Data Flow
1. User interacts with React UI → Next.js pages/components under app/.
2. UI calls API routes (`/api/chat`, `/api/stripe/route.ts`, `/api/upload-picture`) via fetch or streaming RPC style.
3. API handlers authenticate via Clerk middleware → authorize requests.
4. Chat handler uses Vercel AI SDK to fan-out requests to different LLM endpoints and streams responses back to the client.
5. Chat memory is read/write in Upstash Redis; usage metrics and rate limits validated.
6. Billing events (subscription creation, payments) go through Stripe API → webhooks update Neon PostgreSQL via subscription-actions.
7. Upload-picture handler stores images in object storage (cloud bucket or your choice) and returns secure URLs.
8. Reporting endpoint (`/api/send-report`) aggregates data from Redis and PostgreSQL to generate usage reports.
c. Architectural Patterns & Principles
- Generative UI (streaming React components).
- Edge/serverless functions for low-latency API.
- Clear separation of concerns: UI vs. API vs. data.
- Modular business logic in lib/ for testability and reuse.
d. Key Technologies & Frameworks
- Next.js App Router (React 18+ server/client components)
- Vercel AI SDK
- Clerk for auth
- Upstash Redis (KV)
- Neon PostgreSQL (serverless)
- Stripe (billing + webhooks)
- pnpm, TypeScript, Tailwind/CSS modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Tier
    subgraph "Frontend Tier"
        direction TB
        Browser["User Browser (React UI)"]:::frontend
        UIComponents["UI Components\n(chat-form, chat-messages,\nui/**, use-streamable-text)"]:::frontend
    end

    %% Backend Tier
    subgraph "Backend Tier"
        direction TB
        ClerkMiddleware["Auth Middleware (Clerk)"]:::business
        subgraph "API Routes"
            direction TB
            ChatAPI["Chat API\n(Vercel AI SDK, ai.ts,\nchat-config, model-config)"]:::business
            StripeAPI["Stripe Handler\n(stripe route)"]:::business
            UploadAPI["Upload Handler\n(upload-picture route)"]:::business
            ReportAPI["Report Handler\n(send-report route)"]:::business
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Redis["Upstash Redis"]:::database
        Postgres["Neon PostgreSQL"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ClerkService["Clerk Auth"]:::external
        LLM["LLM Vendors"]:::external
        StripeService["Stripe"]:::external
        Storage["Object Storage"]:::external
    end

    %% Connections
    Browser -->|uses| UIComponents
    UIComponents -->|fetch/stream| ClerkMiddleware
    ClerkMiddleware --> ChatAPI
    ClerkMiddleware --> StripeAPI
    ClerkMiddleware --> UploadAPI
    ClerkMiddleware --> ReportAPI

    ChatAPI -->|"stream requests"| LLM
    ChatAPI -->|read/write| Redis
    StripeAPI -->|sync| StripeService
    StripeAPI -->|update| Postgres
    UploadAPI -->|store images| Storage
    ReportAPI -->|read| Redis
    ReportAPI -->|read| Postgres

    StripeService -->|webhook events| StripeAPI

    %% Click Events
    click Browser "https://github.com/snsa-kscc/edureteai/blob/main/app/(app)/layout.tsx"
    click UIComponents "https://github.com/snsa-kscc/edureteai/tree/main/components/"
    click ClerkMiddleware "https://github.com/snsa-kscc/edureteai/blob/main/middleware.ts"
    click ChatAPI "https://github.com/snsa-kscc/edureteai/blob/main/app/(app)/api/chat/route.ts"
    click StripeAPI "https://github.com/snsa-kscc/edureteai/blob/main/app/(app)/api/stripe/route.ts"
    click UploadAPI "https://github.com/snsa-kscc/edureteai/blob/main/app/(app)/api/upload-picture/route.ts"
    click ReportAPI "https://github.com/snsa-kscc/edureteai/blob/main/app/(app)/api/send-report/route.ts"
    click ChatAPI "https://github.com/snsa-kscc/edureteai/blob/main/app/(app)/ai.ts"
    click ChatAPI "https://github.com/snsa-kscc/edureteai/blob/main/lib/chat-config.ts"
    click ChatAPI "https://github.com/snsa-kscc/edureteai/blob/main/lib/model-config.ts"
    click Redis "https://github.com/snsa-kscc/edureteai/blob/main/lib/redis-actions.ts"
    click Postgres "https://github.com/snsa-kscc/edureteai/blob/main/lib/neon-actions.ts"
    click Postgres "https://github.com/snsa-kscc/edureteai/blob/main/db/schema.ts"
    click Postgres "https://github.com/snsa-kscc/edureteai/blob/main/migrations/002_add_message_counts.sql"
    click Postgres "https://github.com/snsa-kscc/edureteai/blob/main/migrations/003_add_subscriptions.sql"
    click Postgres "https://github.com/snsa-kscc/edureteai/blob/main/migrations/004_add_subscription_pending_fields.sql"
    click StripeService "https://github.com/snsa-kscc/edureteai/blob/main/lib/stripe.ts"
    click StripeService "https://github.com/snsa-kscc/edureteai/blob/main/lib/subscription-actions.ts"
    click StripeService "https://github.com/snsa-kscc/edureteai/blob/main/lib/subscription-utils.ts"
    click UploadAPI "https://github.com/snsa-kscc/edureteai/blob/main/lib/upload-actions.ts"
    click UploadAPI "https://github.com/snsa-kscc/edureteai/blob/main/hooks/use-image-upload.ts"
    click ReportAPI "https://github.com/snsa-kscc/edureteai/blob/main/lib/xlsx-actions.ts"
    click UIComponents "https://github.com/snsa-kscc/edureteai/blob/main/components/chat/chat-form.tsx"
    click UIComponents "https://github.com/snsa-kscc/edureteai/blob/main/components/chat/chat-messages.tsx"
    click UIComponents "https://github.com/snsa-kscc/edureteai/blob/main/hooks/use-streamable-text.tsx"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef business fill:#90EE90,stroke:#333,stroke-width:1px
    classDef database fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
