How rayquaza17/sol works
Project type & purpose (from file tree)
This is a Next.js (App Router) web application implementing a chatbot experience (“solitude-chatbot”), with:
• A UI under app/ (pages like /chat, /auth, /dashboard, marketing pages).
• A server-side API route under app/api/chat/route.ts for chat requests.
• A local AI orchestration/guardrails engine under lib/ai/engine/* (intent, state, memory, stage tracking, safety/crisis monitoring).
• A Supabase integration via lib/supabaseClient.ts (likely auth + persistence).
• Additional prompt/output hardening via lib/promptConstructor.ts and lib/outputGuard.ts.
Server / API layer (still Next.js)
• app/api/chat/route.ts: server endpoint for chat.
Domain / AI engine layer
• lib/ai/engine/engine.ts: likely the orchestrator entrypoint.
• intent.ts, state.ts, types.ts, domain.ts: domain model + intent classification.
• memory.ts: conversation memory handling (important: where memory is stored).
• stage-tracker.ts: conversation stage tracking.
• safety-monitor.ts, crisisMonitor.ts: safety/crisis detection and routing.
• lib/promptConstructor.ts: prompt assembly.
• lib/outputGuard.ts: output filtering/guardrails.
Data / External services
• lib/supabaseClient.ts: Supabase service boundary (Auth, DB, Storage).
• Potential external LLM provider (not visible in tree): confirm in package.json (e.g., openai, @anthropic-ai/sdk, ai, etc.) and in env vars.
• Static data: app/data/quotes.json.
Engine
• loads/updates State (state.ts)
• queries/updates Memory (memory.ts)
• runs Intent detection (intent.ts)
• runs Safety/Crisis monitors (safety-monitor.ts, crisisMonitor.ts)
• builds prompt via PromptConstructor
AuthProvider.tsx manages session/token client-side
If the code doesn’t yet persist chat history, represent memory as in-process (component) and annotate “optional persistence”.
Architectural patterns to call out
From the engine folder, this looks like a pipeline/orchestrator pattern:
• A central orchestrator (engine.ts) coordinating modular steps:
• classification (intent)
• state/memory management
• stage tracking
• safety/crisis gating
• prompt construction
• output validation
guardrails as first-class:
• Safety/crisis checks are not incidental utilities; they’re core decision points. Put them on the critical path before and after the LLM call (pre-checks and post-checks).
What technologies to label (don’t guess; verify)
• Next.js App Router (based on app/ + route.ts)
• TypeScript (.ts/.tsx, tsconfig.json)
• Supabase (supabaseClient.ts)
• The specific LLM provider (check package.json and env vars)
• Whether chat uses streaming responses (check route.ts implementation)
• Whether memory is stored in Supabase DB, Redis, or in-memory
Practical “how to be accurate” checklist (based on this repo)
• lib/ai/engine/engine.ts: the real pipeline order and decision points
• lib/ai/engine/memory.ts: where memory lives (in-memory vs Supabase)
• lib/supabaseClient.ts + app/context/AuthProvider.tsx: auth/session model
• package.json: confirms AI SDK and any additional infra (analytics, monitoring, etc.)
That set will be detailed, reviewable, and tightly grounded in the file tree you have.