# orelchalfon/raayentiai architecture

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

- Interactive diagram: https://gitdiagram.com/orelchalfon/raayentiai
- Repository: https://github.com/orelchalfon/raayentiai

## Overview

##### Project type and purpose
- RaayentiAI is a full-stack, Next.js (App Router) application written in TypeScript that delivers an AI-powered tutoring platform.
- It offers user-facing pages (React components under the `app` and `components` directories), server-side API routes (`app/api/sentry-example-api/route.ts`), and integrates with a database (Supabase) and external AI services for personalized tutoring.

##### File structure
- Top-level “app” folder: Next.js 13 App Router structure containing page.tsx, layout.tsx, global CSS, error handling, and nested routes (e.g., `/companions`, `/my-journey`, `/sign-in`, `/subscription`).
- `app/api/...`: Serverless API route(s) executed on Next.js server/Edge.
- `components`: Reusable UI primitives, layouts, forms, cards, navigation; grouped by function (e.g., `ui` for design system atoms).
- `lib`: Business logic and integrations – Supabase client (`lib/supabase.ts`), companion actions (`lib/actions/companion.action.ts`), utility functions, and a VAPI SDK wrapper.
- Configuration & instrumentation: `next.config.ts`, `middleware.ts`, Sentry edge/server configs, `instrumentation.ts`, and Tailwind/PostCSS configs.
- Types, constants, and environment: TypeScript declarations and JSON constants.

##### Extract architectural insights from the README
- Confirms multi-subject AI tutoring, interactive Q&A, progress tracking.
- Technology callouts include TypeScript, Next.js (implied React/Node), and external AI/analytics services.

##### Main components and interactions
a. Client Layer
– Web Browser / Mobile Browser (Next.js SSR + CSR)
– React Server & Client Components (pages under `app/…`)
b. Edge / API Layer
– Next.js App Router server runtime (Edge Functions or Node)
– API endpoints (e.g., `/api/sentry-example-api`)
c. Business Logic / Service Layer
– Companion actions and tutoring workflows (`lib/actions`)
– Supabase SDK (`lib/supabase.ts`) for user data, progress, session management
– VAPI SDK (`lib/vapi.sdk.ts`) as AI integration wrapper
d. Data & External Services
– Supabase Database (Postgres)
– AI Service (e.g., OpenAI or custom model via VAPI)
– Sentry (Error/Performance Monitoring)
e. Static Assets & CDN
– Next.js Static file serving (under `public/`)
– CSS & Tailwind/PostCSS pipeline

##### Architectural patterns and design principles
- Component-based UI (atomic design in `components/ui`)
- Separation of concerns: UI vs. business logic vs. data layer
- Serverless/Edge functions for API routes and monitoring (Sentry)
- Modular state & actions in `lib/actions` for testability and reuse
- App Router for nested routing and layouts (Next.js 13 conventions)

– Clear labels for each component (e.g., “Next.js App Router”, “Supabase DB”, “OpenAI API”)
– Notes on technologies: “Node.js runtime”, “TypeScript”, “React Server Components”, “Edge Function”
– Deployment artifacts: Next.js build, static export, Edge configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Web/Mobile Browser"]:::external
        AppRouter["Next.js App Router (Pages & Layouts)"]:::frontend
        Browser -->|"HTTP/HTTPS"| AppRouter

        subgraph "Rendering Components"
            direction TB
            Layouts["Global Layout & Styles"]:::frontend
            Pages["User-Facing Pages"]:::frontend
        end

        AppRouter --> Layouts
        AppRouter --> Pages

        subgraph "Pages"
            direction TB
            Home["Home Page"]:::frontend
            CompList["Companions List"]:::frontend
            CompDetail["Companion Detail"]:::frontend
            CompNew["New Companion Form"]:::frontend
            Journey["My Journey"]:::frontend
            SignIn["Sign-In Flow"]:::frontend
            Subscription["Subscription Page"]:::frontend
            SentryPage["Sentry Example Page"]:::frontend
        end

        Pages --> Home
        Pages --> CompList
        Pages --> CompDetail
        Pages --> CompNew
        Pages --> Journey
        Pages --> SignIn
        Pages --> Subscription
        Pages --> SentryPage
    end

    %% API / Edge Layer
    subgraph "Edge / API Layer"
        direction TB
        NextServer["Next.js Server Runtime / Edge Function"]:::backend
        API["Serverless API Routes"]:::backend
        AppRouter --> NextServer
        NextServer --> API

        SentryAPI["Sentry Example API Route"]:::backend
        API --> SentryAPI
    end

    %% Business Logic / Service Layer
    subgraph "Service Layer"
        direction TB
        CompanionAction["Companion Workflows"]:::backend
        SupabaseClient["Supabase Client & Helpers"]:::backend
        VAPI["VAPI SDK (AI Integration)"]:::backend

        API --> CompanionAction
        CompanionAction --> SupabaseClient
        CompanionAction --> VAPI
    end

    %% Data & External Services
    subgraph "Data & External Services"
        direction TB
        SupabaseDB["Supabase Database (Postgres)"]:::external
        OpenAI["OpenAI / AI Service"]:::external
        SentryExt["Sentry (Monitoring)"]:::external

        SupabaseClient --> SupabaseDB
        VAPI --> OpenAI
        NextServer --> SentryExt
        API --> SentryExt
    end

    %% Static Assets & CDN
    subgraph "Static Assets & CDN"
        direction TB
        PublicAssets["Static Assets (public/)"]:::static
        StylesPipeline["CSS & Tailwind Pipeline"]:::static

        AppRouter --> PublicAssets
        AppRouter --> StylesPipeline
    end

    %% Click Events
    click AppRouter "https://github.com/orelchalfon/raayentiai/tree/main/app/"
    click Layouts "https://github.com/orelchalfon/raayentiai/blob/main/app/layout.tsx"
    click Layouts "https://github.com/orelchalfon/raayentiai/blob/main/app/globals.css"
    click Layouts "https://github.com/orelchalfon/raayentiai/blob/main/app/global-error.tsx"
    click Home "https://github.com/orelchalfon/raayentiai/blob/main/app/page.tsx"
    click CompList "https://github.com/orelchalfon/raayentiai/blob/main/app/companions/page.tsx"
    click CompDetail "https://github.com/orelchalfon/raayentiai/blob/main/app/companions/[id]/page.tsx"
    click CompNew "https://github.com/orelchalfon/raayentiai/blob/main/app/companions/new/page.tsx"
    click Journey "https://github.com/orelchalfon/raayentiai/blob/main/app/my-journey/page.tsx"
    click Journey "https://github.com/orelchalfon/raayentiai/blob/main/app/my-journey/loading.tsx"
    click SignIn "https://github.com/orelchalfon/raayentiai/blob/main/app/sign-in/[[...sign-in]]/page.tsx"
    click Subscription "https://github.com/orelchalfon/raayentiai/blob/main/app/subscription/page.tsx"
    click SentryPage "https://github.com/orelchalfon/raayentiai/blob/main/app/sentry-example-page/page.tsx"
    click SentryAPI "https://github.com/orelchalfon/raayentiai/blob/main/app/api/sentry-example-api/route.ts"
    click CompanionAction "https://github.com/orelchalfon/raayentiai/blob/main/lib/actions/companion.action.ts"
    click SupabaseClient "https://github.com/orelchalfon/raayentiai/blob/main/lib/supabase.ts"
    click VAPI "https://github.com/orelchalfon/raayentiai/blob/main/lib/vapi.sdk.ts"
    click PublicAssets "https://github.com/orelchalfon/raayentiai/tree/main/public/"
    click PublicAssets "https://github.com/orelchalfon/raayentiai/tree/main/public/icons/"
    click PublicAssets "https://github.com/orelchalfon/raayentiai/tree/main/public/images/"
    click PublicAssets "https://github.com/orelchalfon/raayentiai/tree/main/public/readme/"
    click StylesPipeline "https://github.com/orelchalfon/raayentiai/blob/main/postcss.config.mjs"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0077CC,color:#000
    classDef backend fill:#DFF2D8,stroke:#339900,color:#000
    classDef external fill:#FFE8D0,stroke:#CC7000,color:#000
    classDef static fill:#F0F0F0,stroke:#888888,color:#000
```
