# asiertxo09/mvp-ai architecture

> Architecture diagram of the GitHub repository asiertxo09/mvp-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asiertxo09/mvp-ai
- Repository: https://github.com/asiertxo09/mvp-ai

## Overview

A. Project Type and Purpose
##### This is a full-stack, serverless application (“EduPlay”) combining
- A static, single-page frontend served via Cloudflare Pages
- Cloudflare Workers functions as the API layer (D1/SQLite backing store)
- A dedicated Node.js “ai-backend-groq” service for AI‐powered text, image, and audio processing
- Optional Python microservices (SDXL image and ASR/TTS audio) for local inference

B. Key File-Structure Insights
##### Top-level folders
- frontend/ – static HTML/CSS/JS, Cloudflare Workers in functions/, DB migrations in migrations/
- ai-backend-groq/ – Node.js server exposing AI endpoints (generate, transcribe, image)
- docs/ – developer guides
##### Configuration and deployment files
- frontend/wrangler.toml – Cloudflare Pages + Functions config
- ai-backend-groq/.env.example – environment variables for Groq and Hugging Face
- render.yaml – render.com deployment hints
3. Absence of ai-services-local in the file tree suggests it may be maintained separately but is described in README as optional Python microservices.

C. Architecture Overview (per README)
Browser → Cloudflare Pages (frontend + Workers) → D1 (SQLite)
│
└──▶ ai-backend-groq (Node.js)
└──▶ External Groq API / Hugging Face
└──▶ ai-services-local Python services (SDXL & Audio)

##### Cloudflare Pages CDN – Hosts static assets (HTML, CSS, JS, images).
3. Cloudflare Workers Functions – API gateway for /api/* routes, session middleware, D1 binding.
##### Node.js Backend (ai-backend-groq) – Express/Fastify-style server for
- /api/generate → Groq text generation
- /api/transcribe → ASR via Python or Hugging Face
- /api/image → SDXL via local service or Hugging Face
##### Python Microservices (optional) – FastAPI services
- SDXL image service (port 5005)
- Audio service with ASR and TTS (port 5006)
##### External AI APIs – Groq API, Hugging Face inference endpoints.

E. Relationships & Interactions
##### Node.js Backend → Local Python services (HTTP) if LOCAL_* URLs configured.

F. Architectural Patterns & Principles
##### Clear separation of concerns
- Presentation layer (static site + client-side logic)
- API layer (Workers)
- Business logic (Node.js AI backend)
- Specialized inference microservices (Python)
3. API Gateway pattern: Workers route and authenticate requests before passing to Node backend or DB.
4. Microservices for AI workloads, pluggable via environment variables (LOCAL_SDXL_URL, LOCAL_ASR_URL).

##### Frontend Focus
- D1 under Workers for database interactions.
##### Backend Focus
- Inside it, list sub-components: Groq client, Hugging Face client, asset generation scripts.
##### Microservices & External
- SDXL and Audio services under “Python Microservices” with ports 5005/5006.

##### Browser at the left, pointing to CDN.
5. In the backend block, show three internal API endpoints (/generate, /transcribe, /image) and their downstream calls to Python services or external APIs.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Client"
    Browser["Client / Browser"]:::client
  end

  subgraph "CDN"
    Pages["Cloudflare Pages CDN"]:::serverless
    StaticAssets["Static Assets (HTML/CSS/JS)"]:::static
  end

  subgraph "Workers"
    Middleware["Session & Auth Middleware"]:::serverless
    APIRoutes["API Routes (/api/*)"]:::serverless
  end

  subgraph "Database"
    Migrations["DB Migrations"]:::devops
    D1Binding["D1 Binding (lib/d1.js)"]:::serverless
    D1["D1 Database (SQLite)"]:::db
  end

  subgraph "Node.js Backend (ai-backend-groq)"
    app["app.py (Server)"]:::backend
    GenAssets["generate_assets.py"]:::backend
    Env[".env.example"]:::backend
    Req["requirements.txt"]:::backend
    Tests["tests/"]:::backend
    gen["/api/generate Endpoint"]:::backend
    trans["/api/transcribe Endpoint"]:::backend
    img["/api/image Endpoint"]:::backend
  end

  subgraph "Python Microservices (Optional)"
    SDXL["SDXL Image Service (port 5005)"]:::micro
    Audio["Audio Service (ASR/TTS port 5006)"]:::micro
  end

  subgraph "External AI APIs"
    Groq["Groq API"]:::external
    HF["Hugging Face"]:::external
  end

  Browser -->|HTTP GET| Pages
  Pages -->|Serves Assets| Browser
  Pages -->|Invokes| Middleware
  Middleware -->|Routes to| APIRoutes
  APIRoutes -->|SQL Queries| D1Binding
  D1Binding -->|Queries| D1
  APIRoutes -->|HTTPS Calls| app

  app -->|calls| gen
  app -->|calls| trans
  app -->|calls| img

  gen -->|REST| Groq
  trans -->|REST| HF
  trans -->|HTTP| Audio
  img -->|REST| HF
  img -->|HTTP| SDXL

  Migrations -->|Initializes| D1

  click Browser "https://github.com/asiertxo09/mvp-ai/blob/main/frontend/app/index.html"
  click StaticAssets "https://github.com/asiertxo09/mvp-ai/tree/main/frontend/"
  click Pages "https://github.com/asiertxo09/mvp-ai/blob/main/frontend/wrangler.toml"
  click Middleware "https://github.com/asiertxo09/mvp-ai/blob/main/frontend/functions/_middleware.js"
  click APIRoutes "https://github.com/asiertxo09/mvp-ai/tree/main/frontend/functions/api/"
  click Migrations "https://github.com/asiertxo09/mvp-ai/tree/main/frontend/migrations/"
  click D1Binding "https://github.com/asiertxo09/mvp-ai/blob/main/frontend/functions/lib/d1.js"
  click app "https://github.com/asiertxo09/mvp-ai/blob/main/ai-backend-groq/app.py"
  click GenAssets "https://github.com/asiertxo09/mvp-ai/blob/main/ai-backend-groq/generate_assets.py"
  click Env "https://github.com/asiertxo09/mvp-ai/blob/main/ai-backend-groq/.env.example"
  click Req "https://github.com/asiertxo09/mvp-ai/blob/main/ai-backend-groq/requirements.txt"
  click Tests "https://github.com/asiertxo09/mvp-ai/tree/main/ai-backend-groq/tests/"
  click Stats "https://github.com/asiertxo09/mvp-ai/blob/main/render.yaml"

  classDef client fill:#e0f7fa,stroke:#006064,color:#004d40
  classDef serverless fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
  classDef static fill:#c8e6c9,stroke:#1b5e20
  classDef backend fill:#90caf9,stroke:#0d47a1
  classDef db fill:#a5d6a7,stroke:#1b5e20
  classDef micro fill:#ffe082,stroke:#ff6f00
  classDef external fill:#ffcc80,stroke:#e65100
  classDef devops fill:#cfd8dc,stroke:#37474f
```
