# rayquaza17/sol architecture

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

- Interactive diagram: https://gitdiagram.com/rayquaza17/sol
- Repository: https://github.com/rayquaza17/sol

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% System Context (Vertical)
  %% =========================
  subgraph "System Context"
    U["User (Anonymous / Authenticated)"]:::person
    APP["Solitude Chatbot Web App (Next.js App Router)"]:::system
    SB["Supabase (Auth + DB)"]:::external
    LLM["LLM Provider API (TBD)"]:::external
  end

  U -->|"uses"| APP
  APP -->|"auth+db"| SB
  APP -->|"model_inference"| LLM

  %% =========================
  %% Container Diagram
  %% =========================
  subgraph "Container Diagram (Runtime Boundaries)"
    direction TB

    subgraph "Browser (React / Next.js Client)"
      direction TB
      Layout["App Shell / Layout"]:::ui
      Styles["Global Styles"]:::ui
      Components["Reusable UI Components (Navbar/Hero/Footer/etc.)"]:::ui
      Quotes["Static Data (quotes.json)"]:::data

      subgraph "Routes (Pages)"
        direction TB
        Home["Route: / (Marketing Home)"]:::ui
        About["Route: /about"]:::ui
        Contact["Route: /contact"]:::ui
        Features["Route: /features"]:::ui
        Privacy["Route: /privacy"]:::ui
        Resources["Route: /resources"]:::ui
        AuthPage["Route: /auth"]:::ui
        Dashboard["Route: /dashboard"]:::ui
        ChatPage["Route: /chat"]:::ui
      end

      ChatUI["Chat UI (ChatInterface)"]:::ui
      AuthProvider["Auth Session Context Provider"]:::ui
    end

    subgraph "Next.js Server (App Router + Route Handlers)"
      direction TB
      NextConfig["Next.js Runtime/Build Config"]:::server
      ApiChat["API Route: POST /api/chat"]:::api

      subgraph "AI Orchestration & Safety Layer (lib/*)"
        direction TB
        Engine["AI Orchestrator (Engine)"]:::engine

        subgraph "Engine Pipeline Modules"
          direction TB
          Intent["Intent Detection"]:::engine
          State["State Management"]:::engine
          Memory["Conversation Memory"]:::engine
          Stage["Stage Tracking"]:::engine
          Safety["Safety Monitor (guardrails)"]:::guard
          Crisis["Crisis Monitor (guardrails)"]:::guard
          Prompt["Prompt Construction"]:::engine
          Output["Output Guard / Response Filtering"]:::guard
          Domain["Domain Model"]:::engine
          Types["Types / Contracts"]:::engine
          SupabaseClient["Supabase Client Integration"]:::server
        end
      end
    end
  end

  %% Client -> Server
  ChatUI -->|"1.POST_/api/chat"| ApiChat
  AuthProvider -->|"session_token"| ApiChat

  %% Server orchestration flow (numbered, vertical)
  ApiChat -->|"2.invoke"| Engine
  Engine -->|"3.load/update"| State
  Engine -->|"4.fetch/update"| Memory
  Engine -->|"5.classify"| Intent
  Engine -->|"6.track_stage"| Stage
  Engine -->|"7.precheck"| Safety
  Engine -->|"8.precheck"| Crisis
  Engine -->|"9.construct_prompt"| Prompt
  Prompt -->|"10.use_schema"| Domain
  Prompt -->|"11.use_contracts"| Types
  Engine -->|"12.call_model"| LLM
  LLM -->|"13.model_output"| Engine
  Engine -->|"14.postfilter"| Output
  Output -->|"15.response"| ApiChat
  ApiChat -->|"16.render_reply"| ChatUI

  %% Optional persistence/auth interactions
  Memory -->|"optional_persist/read"| SupabaseClient
  ApiChat -->|"auth/user_lookup"| SupabaseClient
  SupabaseClient -->|"connects"| SB

  %% App composition
  Layout -->|"wraps"| Components
  Layout -->|"provides"| AuthProvider
  Layout -->|"styles"| Styles
  ChatPage -->|"renders"| ChatUI
  Resources -->|"may_use"| Quotes

  %% Context links to containers
  U -->|"navigates"| Home
  U -->|"navigates"| ChatPage
  U -->|"navigates"| AuthPage
  U -->|"navigates"| Dashboard
  ApiChat -->|"uses"| SB
  ApiChat -->|"uses"| LLM

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click ChatUI "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/chat/ChatInterface.tsx"
  click ChatPage "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/chat/page.tsx"
  click AuthProvider "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/context/AuthProvider.tsx"
  click Components "https://github.com/rayquaza17/sol/tree/main/solitude-chatbot/app/components/"
  click About "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/about/page.tsx"
  click Contact "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/contact/page.tsx"
  click Features "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/features/page.tsx"
  click Privacy "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/privacy/page.tsx"
  click Resources "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/resources/page.tsx"
  click Home "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/page.tsx"
  click AuthPage "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/auth/page.tsx"
  click Dashboard "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/dashboard/page.tsx"
  click Layout "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/layout.tsx"
  click Styles "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/globals.css"
  click ApiChat "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/api/chat/route.ts"
  click Engine "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/engine.ts"
  click Intent "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/intent.ts"
  click State "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/state.ts"
  click Memory "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/memory.ts"
  click Stage "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/stage-tracker.ts"
  click Safety "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/safety-monitor.ts"
  click Crisis "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/crisisMonitor.ts"
  click Domain "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/domain.ts"
  click Types "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/ai/engine/types.ts"
  click Prompt "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/promptConstructor.ts"
  click Output "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/outputGuard.ts"
  click SupabaseClient "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/lib/supabaseClient.ts"
  click Quotes "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/app/data/quotes.json"
  click NextConfig "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/next.config.ts"
  click APP "https://github.com/rayquaza17/sol/blob/main/solitude-chatbot/package.json"

  %% =========================
  %% Styles (Color Required)
  %% =========================
  classDef person fill:#FFF4CC,stroke:#8A6D00,stroke-width:1px,color:#1b1b1b
  classDef system fill:#D7F5E9,stroke:#0B6B4F,stroke-width:1px,color:#0b2a20
  classDef ui fill:#E6F0FF,stroke:#2F5DB3,stroke-width:1px,color:#0a1f44
  classDef server fill:#EAF2F2,stroke:#2C6E6F,stroke-width:1px,color:#083132
  classDef api fill:#DFF7FF,stroke:#0F7EA1,stroke-width:1px,color:#08303c
  classDef engine fill:#F1E6FF,stroke:#6B3FA0,stroke-width:1px,color:#2b1245
  classDef guard fill:#FFE6E6,stroke:#B3261E,stroke-width:1px,color:#3b0b0b
  classDef external fill:#EFEFEF,stroke:#666666,stroke-width:1px,color:#1f1f1f
  classDef data fill:#FFF1D6,stroke:#A46A00,stroke-width:1px,color:#3a2400
```
