How sergi335/dream-reader works
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).