# three7vn/desthetik architecture

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

- Interactive diagram: https://gitdiagram.com/three7vn/desthetik
- Repository: https://github.com/three7vn/desthetik

## Overview

##### Project Type and Purpose
- Desthetik is a full-stack, open-source “system design co-pilot.”
- Frontend: React/Next.js app (TypeScript) that captures user ideas (voice or text) and renders visual flowcharts using React Flow.
- Backend: A Python microservice (backend/main.py) and/or Next.js API routes (pages/api/prompts.ts) orchestrating prompt generation and LLM calls.

##### File-Structure Analysis
Top-Level Directories:
- backend/           – Python service (requirements.txt) for LLM orchestration and business logic
- pages/             – Next.js routes and API endpoints (pages/api/prompts.ts)
- components/        – Reusable UI pieces (FlowCanvas.tsx, Sidebar.tsx, Voice.tsx, ContactModal.tsx, LoadingSkeleton.tsx)
- public/            – Static assets (e.g., Desthetik.png)
- styles/            – Global CSS
Configuration/Build:
- package.json, tsconfig.json, next.config.js – Frontend build and type settings
- requirements.txt – Python dependencies for the backend
Tests:
- backend/test_api.py – Basic integration tests for the Python service

##### README Insights
- The system accepts multi-turn, conversational inputs (voice or text).
- It dynamically selects a “graph type” based on user context and maps user answers to nodes & edges.
- Uses React Flow in the browser to render graphs; calls an LLM (OpenAI or similar) on the backend.

a. Main Components
1. User Device / Browser
- Voice Input (Web Speech API) – Voice.tsx
- UI Shell (_app.tsx) with Sidebar, ContactModal, LoadingSkeleton
- FlowCanvas (React Flow) for rendering the graph
2. Next.js Frontend Server
- SSR/CSR pages (pages/index.tsx)
- REST API endpoint (pages/api/prompts.ts)
3. Python Backend Service
- main.py – Receives prompt payloads from Next.js or directly from client
- test_api.py – Verifies LLM orchestration
4. LLM Provider (External)
- OpenAI API or other LLM endpoint
5. (Optional) Hosting/Storage
- Vercel/AWS Lambda for Next.js
- AWS/GCP/Azure or Docker for Python service
- CDN for public assets

b. Relationships & Data Flows
1. User speaks → Voice.tsx captures audio → Web Speech API transcribes to text.
2. Client component packages multi-turn form data → POST to Next.js API (/api/prompts).
3. Next.js API route either:
- Directly calls LLM (node-sdk)
- Or forwards to Python backend (HTTP) for advanced orchestration.
4. Python service composes system-design prompt → calls external LLM API → returns structured graph JSON.
5. Next.js endpoint returns graph data to client.
6. FlowCanvas component ingests JSON → React Flow renders nodes & edges.
7. User can download/export PNG or JSON.

c. Architectural Patterns & Principles
- Separation of concerns: UI vs. orchestration vs. LLM.
- API Gateway pattern: Next.js API routes as a single public interface.
- Microservice for specialized logic (Python).
- Graph-oriented rendering (React Flow) on the client.

d. Key Technologies & Frameworks
- Next.js (React SSR/CSR)
- React Flow (visual layout library)
- Web Speech API (voice capture)
- Python (Flask/FastAPI or plain HTTP) for LLM prompt logic
- OpenAI or similar LLM endpoint

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        A1["Voice.tsx\n(Web Speech API)"]:::frontend
        A2["FlowCanvas.tsx\n(React Flow)"]:::frontend
        A3["_app.tsx\n(UI Shell)"]:::frontend
        A4["Sidebar.tsx"]:::frontend
        A5["ContactModal.tsx"]:::frontend
        A6["LoadingSkeleton.tsx"]:::frontend
        A7["index.tsx\n(SSR/CSR)"]:::frontend
        A8["globals.css"]:::frontend
        A9["package.json\n tsconfig.json\n next.config.js"]:::frontend
        A10["public/\n(Static Assets)"]:::frontend
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        direction TB
        B1["prompts.ts\n(API Gateway)"]:::backend
        B2["main.py\n(LLM Orchestration)"]:::backend
        B3["test_api.py\n(Integration Tests)"]:::backend
        B4["requirements.txt"]:::backend
    end

    %% External Layer
    subgraph "External"
        direction TB
        C1["OpenAI API\n(LLM Provider)"]:::external
        C2["JSON Payload"]:::external
    end

    %% Data Flows
    A1 -->|"transcribed text"| A3
    A3 --> A7
    A7 -->|"POST /api/prompts"| B1
    B1 -->|"forward prompt"| B2
    B2 -->|"calls LLM"| C1
    C1 -->|"graph JSON"| B2
    B2 --> C2
    B2 --> B1
    B1 -->|"returns graph JSON"| A2

    %% Click Events
    click A1 "https://github.com/three7vn/desthetik/blob/main/components/Voice.tsx"
    click A2 "https://github.com/three7vn/desthetik/blob/main/components/FlowCanvas.tsx"
    click A3 "https://github.com/three7vn/desthetik/blob/main/pages/_app.tsx"
    click A4 "https://github.com/three7vn/desthetik/blob/main/components/Sidebar.tsx"
    click A5 "https://github.com/three7vn/desthetik/blob/main/components/ContactModal.tsx"
    click A6 "https://github.com/three7vn/desthetik/blob/main/components/LoadingSkeleton.tsx"
    click A7 "https://github.com/three7vn/desthetik/blob/main/pages/index.tsx"
    click B1 "https://github.com/three7vn/desthetik/blob/main/pages/api/prompts.ts"
    click B2 "https://github.com/three7vn/desthetik/blob/main/backend/main.py"
    click B3 "https://github.com/three7vn/desthetik/blob/main/backend/test_api.py"
    click A10 "https://github.com/three7vn/desthetik/tree/main/public/"
    click A8 "https://github.com/three7vn/desthetik/blob/main/styles/globals.css"
    click A9 "https://github.com/three7vn/desthetik/blob/main/package.json"
    click B4 "https://github.com/three7vn/desthetik/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef backend fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef external fill:#fff9c4,stroke:#fdd835,color:#f57f17;
```
