# shlomoc/roast architecture

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

- Interactive diagram: https://gitdiagram.com/shlomoc/roast
- Repository: https://github.com/shlomoc/roast

## Overview

##### Project Type and Purpose
- This is a full-stack, server-rendered React web application built with Next.js 14 (app directory) and Tailwind CSS, exposing two REST API routes for AI roasting and TTS.
- Purpose: Accept a user’s photo, call external AI services (OpenRouter for roast text, ElevenLabs for speech), and present the results in a privacy-focused UI.

##### Main Components
a. Client Browser (React/Next.js)
b. Next.js Server (app router, serverless functions)
- API Route: `/api/roast` (image → OpenRouter AI → roast text)
- API Route: `/api/tts` (roast text → ElevenLabs TTS → audio)
c. UI Library & Static Assets
- Tailwind CSS, shadcn/ui components under `src/components/ui`
- Public folder for static files
d. Utility Layer
- `src/lib/utils.ts` for shared helpers
e. External Services
- OpenRouter.ai (AI vision + LLM models)
- ElevenLabs.io (Text-to-Speech)

##### Relationships & Data Flow
- User interacts with UI (upload or camera capture) → front-end posts image to `/api/roast`.
- Next.js API handler forwards image + parameters (model, intensity) to OpenRouter.
- OpenRouter returns roast text → Next.js returns JSON roast to front-end.
- User clicks “Play Roast” → front-end calls `/api/tts` with roast text.
- Next.js sends text to ElevenLabs → receives audio stream/URL → front-end plays audio.

##### Architectural Patterns & Design Principles
- Monolithic Next.js app with “app router” paradigm: pages, server components, and edge/serverless functions.
- Separation of concerns: UI components (`src/components`), styles (`globals.css`), business logic (`src/lib/utils.ts`), and API functions (`src/app/api/…`).
- Ephemeral processing: no persistent database or file storage; external APIs handle AI and TTS workloads.
- Environment-based configuration (`.env.local`) for secret keys.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Client Browser\n(React/Next.js)"]:::frontend
        Page["page.tsx"]:::frontend
        Layout["layout.tsx"]:::frontend
        Button["button.tsx"]:::ui
        Card["card.tsx"]:::ui
        Select["select.tsx"]:::ui
        Slider["slider.tsx"]:::ui
        Globals["globals.css"]:::frontend
        Public["public/"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        direction TB
        API_Roast["/api/roast\nroute.ts"]:::backend
        API_TTS["/api/tts\nroute.ts"]:::backend
        Utils["utils.ts"]:::utils
        NextConfig["next.config.ts"]:::config
        TSConfig["tsconfig.json"]:::config
        Env[".env.local"]:::config
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenRouter["OpenRouter.ai"]:::external
        ElevenLabs["ElevenLabs.io"]:::external
    end

    %% Connections
    Browser -->|"renders via"| Page
    Browser -->|"renders via"| Layout
    Page -->|"uses"| Button
    Page -->|"uses"| Card
    Page -->|"uses"| Select
    Page -->|"uses"| Slider
    Layout -->|"imports styles"| Globals

    Browser -->|"POST image\nmultipart/form-data"| API_Roast
    API_Roast -->|"HTTP POST\nroast request"| OpenRouter
    OpenRouter -->|"JSON {roastText}"| API_Roast
    API_Roast -->|"JSON {roastText}"| Browser

    Browser -->|"POST text\nJSON {roastText}"| API_TTS
    API_TTS -->|"HTTP POST\nTTS request"| ElevenLabs
    ElevenLabs -->|"audio/mpeg stream"| API_TTS
    API_TTS -->|"audio/mpeg URL/stream"| Browser

    API_Roast -->|"uses"| Utils
    API_TTS -->|"uses"| Utils
    API_Roast -->|"reads config"| Env
    API_TTS -->|"reads config"| Env
    API_Roast -->|"reads config"| NextConfig
    API_TTS -->|"reads config"| NextConfig
    API_Roast -->|"reads config"| TSConfig
    API_TTS -->|"reads config"| TSConfig

    %% Click Events
    click Page "https://github.com/shlomoc/roast/blob/main/src/app/page.tsx"
    click Layout "https://github.com/shlomoc/roast/blob/main/src/app/layout.tsx"
    click Button "https://github.com/shlomoc/roast/blob/main/src/components/ui/button.tsx"
    click Card "https://github.com/shlomoc/roast/blob/main/src/components/ui/card.tsx"
    click Select "https://github.com/shlomoc/roast/blob/main/src/components/ui/select.tsx"
    click Slider "https://github.com/shlomoc/roast/blob/main/src/components/ui/slider.tsx"
    click Globals "https://github.com/shlomoc/roast/blob/main/src/app/globals.css"
    click Public "https://github.com/shlomoc/roast/tree/main/public/"
    click API_Roast "https://github.com/shlomoc/roast/blob/main/src/app/api/roast/route.ts"
    click API_TTS "https://github.com/shlomoc/roast/blob/main/src/app/api/tts/route.ts"
    click Utils "https://github.com/shlomoc/roast/blob/main/src/lib/utils.ts"
    click NextConfig "https://github.com/shlomoc/roast/blob/main/next.config.ts"
    click TSConfig "https://github.com/shlomoc/roast/blob/main/tsconfig.json"
    click Env "https://github.com/shlomoc/roast/blob/main/.env.local"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef utils fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef config fill:#E8D0FF,stroke:#333,stroke-width:1px
    classDef ui fill:#B2E0FF,stroke:#333,stroke-width:1px
```
