# meephubub/flashcards architecture

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

- Interactive diagram: https://gitdiagram.com/meephubub/flashcards
- Repository: https://github.com/meephubub/flashcards

## Overview

##### Project type and purpose
- This is a full-stack flashcards application built on Next.js 13’s App Router.
- It combines a React-based front-end (UI pages and components) with serverless API routes for data storage, AI-powered features (question generation, grading, similarity), and a Supabase backend.

##### Main components
a. Front-end (Browser/Client)
- Next.js pages in `app/…/page.tsx`
- React components (e.g., card-display, deck-grid, ai-chat, sidebar)
- Context providers (deck-context, settings-context) and custom hooks
b. Next.js Server / API Layer (Serverless Functions)
- API routes under `app/api/…/route.ts` (decks, cards, progress, settings, import, generate, chat, upload)
- Action handlers under `app/actions/…` (ai-chat, generate-questions, grade-answer, xenova-similarity)
c. Database
- Supabase (PostgreSQL) accessed via `lib/supabase.ts` and the SQL schema in `lib/supabase-schema.sql`
d. Machine Learning & External AI Services
- Local ONNX model loaded via Xenova in `public/models` and invoked in `xenova-similarity`
- (Optionally) OpenAI API keys configured in `lib/api-keys.ts` for AI chat and note generation
e. Static Assets & Other Services
- Static files in `public/` (models, sounds)
- File uploads (handled by `app/api/upload/route.ts`)

##### Relationships & Data Flows
- Browser → Next.js Server: Request pages / invoke server components
- Browser → API Layer: Fetch deck/card data, post progress, trigger AI features
- API Layer → Supabase: CRUD operations on decks, cards, progress, settings
- API Layer → ML/AI Services:
- Local ONNX model for semantic similarity
- External AI (OpenAI) for chat, question/note generation
- API Layer → File Storage (public/uploads) for any assets

##### Architectural patterns & design principles
- Separation of Concerns:
- UI (components + pages) vs. business logic (actions) vs. data (API routes)
- Serverless Micro-Endpoints: each `app/api/.../route.ts` is an isolated function
- React Server Components & Client Components under Next.js App Router
- Context & Hooks for state management (deck-context, settings-context, custom hooks)
- Typed contracts with TypeScript (shared types in `types/`)

##### Technologies & Frameworks
- Next.js 13 App Router (React, Server & Client components)
- Tailwind CSS for styling (`styles/` + `tailwind.config.ts`)
- Supabase for database & auth (`lib/supabase.ts`)
- ONNX/Xenova for on-device model inference (`public/models/...`)
- OpenAI or other LLMs via API (keys in `lib/api-keys.ts`)
- PNPM workspace, PostCSS, TypeScript

##### Essential elements
- Clear component boundaries (frontend vs backend)
- Labels for technologies (Next.js, Supabase, Xenova, OpenAI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Next.js Front-end"
        direction TB
        Browser["Browser/Client"]:::browser
        Pages["Next.js Pages (app/*/page.tsx)"]:::frontend
        Components["React UI Components"]:::frontend
        Contexts["Context Providers"]:::frontend
        Hooks["Custom Hooks"]:::frontend
    end

    %% API Layer
    subgraph "Serverless Functions" 
        direction TB
        APIRoutes["API Routes (app/api/**/route.ts)"]:::api
        Actions["Action Handlers (app/actions/*.ts)"]:::api
        SupabaseClient["Supabase Client & Schema"]:::api
        ExamCache["Exam Cache (lib/exam-cache.ts)"]:::api
        OpenAIKeys["OpenAI API Keys"]:::api
    end

    %% Database
    SupabaseDB["Supabase DB (PostgreSQL)"]:::db

    %% ML/AI Services
    subgraph "ML/AI Services"
        direction TB
        XenovaModel["Xenova ONNX Model"]:::ai
        OpenAIService["External AI (OpenAI)"]:::ai
    end

    %% Static Assets
    subgraph "Static Assets & Files"
        direction TB
        Models["Static ONNX Models"]:::static
        Sounds["Static Sound Assets"]:::static
        Uploads["File Upload Storage"]:::static
    end

    %% Connections
    Browser --> Pages
    Browser --> Components
    Browser --> Contexts
    Browser --> Hooks

    Pages -->|Requests /data| APIRoutes
    Components -->|Uses Actions| Actions
    Contexts -->|State mgmt| Hooks

    APIRoutes -->|CRUD ops| SupabaseClient
    APIRoutes -->|Generate/Q & Grade| Actions
    APIRoutes -->|Cache reads/writes| ExamCache
    APIRoutes -->|Upload files| Uploads

    SupabaseClient -->|Queries| SupabaseDB
    Actions -->|Load model| XenovaModel
    Actions -->|Call API| OpenAIService

    %% Click Events
    click Pages "https://github.com/meephubub/flashcards/tree/main/app"
    click Components "https://github.com/meephubub/flashcards/tree/main/components"
    click Contexts "https://github.com/meephubub/flashcards/blob/main/context/deck-context.tsx"
    click Contexts "https://github.com/meephubub/flashcards/blob/main/context/settings-context.tsx"
    click Hooks "https://github.com/meephubub/flashcards/tree/main/hooks"
    click APIRoutes "https://github.com/meephubub/flashcards/tree/main/app/api"
    click Actions "https://github.com/meephubub/flashcards/tree/main/app/actions"
    click SupabaseClient "https://github.com/meephubub/flashcards/blob/main/lib/supabase.ts"
    click SupabaseClient "https://github.com/meephubub/flashcards/blob/main/lib/supabase-schema.sql"
    click ExamCache "https://github.com/meephubub/flashcards/blob/main/lib/exam-cache.ts"
    click OpenAIKeys "https://github.com/meephubub/flashcards/blob/main/lib/api-keys.ts"
    click XenovaModel "https://github.com/meephubub/flashcards/tree/main/public/models/models/Xenova/all-MiniLM-L6-v2"
    click Sounds "https://github.com/meephubub/flashcards/tree/main/public/sounds"
    click Uploads "https://github.com/meephubub/flashcards/blob/main/app/api/upload/route.ts"

    %% Styles
    classDef browser fill:#cce5ff,stroke:#004085
    classDef frontend fill:#cce5ff,stroke:#004085
    classDef api fill:#d4edda,stroke:#155724
    classDef db fill:#ffe5b4,stroke:#ff8c00,shape:cylinder
    classDef ai fill:#e2d5f2,stroke:#5e42a6
    classDef static fill:#f2f2f2,stroke:#6c757d,stroke-dasharray: 4 2
```
