# sergi335/dream-reader architecture

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

- Interactive diagram: https://gitdiagram.com/sergi335/dream-reader
- Repository: https://github.com/sergi335/dream-reader

## Overview

##### Project type and purpose
- Dream Reader is a full-stack web application built with Next.js 15 (App Router). Its purpose is to provide an authenticated, persistent chat interface that can route user messages to multiple LLM providers and store conversation history in Supabase.

##### File structure
- Top-level “app” directory: implements pages (i18n folders), layouts, and server-side API routes under app/api.
- “components” folder: two major subdivisions
- ai-elements: domain-specific UI for chat (messages, loaders, code blocks, citations)
- ui: low-level building blocks (buttons, inputs, dialogs)
- “hooks” and “context”: client-side state and data-fetching abstractions (chat state, conversations, LLM config)
- “lib”: server-side adapters (Supabase clients, LLM provider abstraction, utilities)
- Config, middleware, and SQL scripts for database schema and RLS policies.
- “public”: static assets; “i18n”: internationalization request helper.

##### README for additional insights
- Technology stack: Next.js, Tailwind CSS + Shadcn/ui, Clerk for auth, Supabase for PostgreSQL, multi-provider LLM integration.
- Functional flow: user auth → select or continue conversation → messages exchanged via API routes → LLM provider client → persist messages in DB.

- Client / Frontend: Next.js pages + React components + Tailwind UI + i18n
- Authentication Service: Clerk (hosted externally)
- API Layer / Serverless Functions: Next.js Route Handlers under app/api/chat and app/api/conversations
- Business Logic & Orchestration: lib/llm-providers.ts, hooks, contexts
- Database: Supabase PostgreSQL (conversations, messages tables)
- External LLM Providers: OpenAI, Anthropic, Groq, Together AI, Ollama, Perplexity, Google Gemini (via configurable base URL)

b. Relationships and interactions
1. User interacts with the React UI → components (chatInput, chatMessages) call client hooks (useChatMessages, useChatState).
2. Hooks issue HTTP calls to Next.js API routes:
‑ POST /api/conversations to fetch/create conversation
‑ POST /api/chat to send a new user message
3. API route handlers (route.ts) invoke server-side lib modules:
‑ Validate user session via Clerk middleware
‑ Read/write conversation & message records in Supabase (lib/supabase-server.ts)
‑ Call the selected LLM provider client (lib/llm-providers.ts)
4. LLM provider responds with assistant message → persisted in Supabase → returned to frontend.
5. Frontend updates UI via React context and hooks.

c. Architectural patterns & design principles
- Layered architecture: UI layer → client hooks/context → API layer → service layer (LLM & DB)
- Hexagonal/adaptor pattern for LLM providers: a single interface with multiple concrete implementations.
- Serverless micro-endpoints: each API route is a self-contained function.
- Componentization and memoization for UI performance.
- Internationalization via Next.js routing and next-intl.

d. Key technologies/frameworks
- Next.js 15 (App Router)
- React + Tailwind CSS + Shadcn/ui
- Clerk (auth)
- Supabase (database)
- Multiple LLM APIs (configurable via env vars)

##### Detail
- Sub-components in the UI layer: ai-elements vs ui primitives.
- Server-side modules: lib/supabase-server.ts vs lib/llm-providers.ts.
- Call out environment-based configuration (LLM provider selection).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Browser / Client UI"
        direction TB
        subgraph "App Router Pages & Layouts" 
            direction TB
            P1["app/layout.tsx"]:::frontend
            P2["app/page.tsx"]:::frontend
            P3["app/[locale]/layout.tsx"]:::frontend
            P4["app/[locale]/page.tsx"]:::frontend
            P5["app/[locale]/dashboard/page.tsx"]:::frontend
        end
        subgraph "React Components"
            direction TB
            C1["components/ai-elements/"]:::frontend
            C2["components/ui/"]:::frontend
            C3["components/chatInput.tsx"]:::frontend
            C4["components/chatMessages.tsx"]:::frontend
        end
        subgraph "Hooks & Context"
            direction TB
            H1["hooks/useChatMessages.ts"]:::frontend
            H2["hooks/useChatState.ts"]:::frontend
            H3["context/conversations-context.tsx"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Next.js App Server (API Routes & SSR/CSR)"
        direction TB
        subgraph "API Routes"
            direction TB
            A1["app/api/chat/route.ts"]:::backend
            A2["app/api/conversations/route.ts"]:::backend
            A3["app/api/conversations/[id]/route.ts"]:::backend
        end
        subgraph "Service Layer"
            direction TB
            S1["lib/llm-providers.ts"]:::backend
            S2["lib/supabase-server.ts"]:::backend
            S3["lib/utils.ts"]:::backend
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        E1["Clerk Auth Service"]:::external
        E2["Supabase PostgreSQL"]:::external
        subgraph "LLM Providers" 
            direction TB
            L1["OpenAI"]:::external
            L2["Anthropic"]:::external
            L3["Groq"]:::external
            L4["Google Gemini"]:::external
        end
    end

    %% Connections
    P3 -->|"uses hooks"| H1
    C3 -->|"calls API"| A1
    C4 -->|"calls API"| A1
    A1 -->|"validate session"| E1
    A1 -->|"read/write"| E2
    A1 -->|"invoke"| S1
    S1 -->|"REST/gRPC"| L1
    S1 -->|"REST/gRPC"| L2
    S1 -->|"REST/gRPC"| L3
    S1 -->|"REST/gRPC"| L4
    E2 -->|"response"| A1
    S1 -->|"assistant reply"| A1
    A1 -->|"response"| C4

    %% Click Events
    click P1 "https://github.com/sergi335/dream-reader/blob/main/app/layout.tsx"
    click P2 "https://github.com/sergi335/dream-reader/blob/main/app/page.tsx"
    click P3 "https://github.com/sergi335/dream-reader/blob/main/app/[locale]/layout.tsx"
    click P4 "https://github.com/sergi335/dream-reader/blob/main/app/[locale]/page.tsx"
    click P5 "https://github.com/sergi335/dream-reader/blob/main/app/[locale]/dashboard/page.tsx"
    click C1 "https://github.com/sergi335/dream-reader/tree/main/components/ai-elements/"
    click C2 "https://github.com/sergi335/dream-reader/tree/main/components/ui/"
    click C3 "https://github.com/sergi335/dream-reader/blob/main/components/chatInput.tsx"
    click C4 "https://github.com/sergi335/dream-reader/blob/main/components/chatMessages.tsx"
    click H1 "https://github.com/sergi335/dream-reader/blob/main/hooks/useChatMessages.ts"
    click H2 "https://github.com/sergi335/dream-reader/blob/main/hooks/useChatState.ts"
    click S1 "https://github.com/sergi335/dream-reader/blob/main/lib/llm-providers.ts"
    click S2 "https://github.com/sergi335/dream-reader/blob/main/lib/supabase-server.ts"
    click A1 "https://github.com/sergi335/dream-reader/blob/main/app/api/chat/route.ts"
    click A2 "https://github.com/sergi335/dream-reader/blob/main/app/api/conversations/route.ts"
    click A3 "https://github.com/sergi335/dream-reader/blob/main/app/api/conversations/[id]/route.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
    classDef external fill:#FFF3E0,stroke:#F57C00,stroke-width:1px
```
