# bvs2006/torusai architecture

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

- Interactive diagram: https://gitdiagram.com/bvs2006/torusai
- Repository: https://github.com/bvs2006/torusai

## Overview

1. **What this repo is**
   - Torus AI is a Next.js 14 app for turning an idea into a build plan, architecture, prompts, and deployment guidance.
   - The architecture centers on a guided planning workflow, backed by AI and a persisted project/state layer.

2. **Top-level app structure**
   - The UI is organized with the Next.js App Router into three main areas: public marketing/landing, authentication, and the authenticated product shell.
   - The `(app)` route group is the core product area; `(auth)` contains login/signup/forgot-password; `app/page.tsx` is the public entry.

3. **Core user journey**
   - The primary flow is: landing/auth → onboarding/workspace/dashboard → planner → AI-generated outputs → team/tools/proposals/blueprint/deploy pages.
   - This is a multi-step product, not a single screen app; each step exposes a different artifact in the planning pipeline.

4. **Planner subsystem**
   - `app/(app)/planner` is the main workflow engine.
   - It branches into idea intake, features, architecture, team/architecture guides, blueprint, and deploy views.
   - Nested pages like `architecture/guide/step/[id]` suggest a stepwise drill-down for architecture guidance.

5. **AI service boundary**
   - The app exposes many AI-focused API routes under `app/api/ai/*`: plan, prompt, fix, propose, recommend-tools, validate-feature, team roles, and master prompt generation.
   - These routes are the server-side boundary between the UI and AI model orchestration.

6. **Search + model selection flow**
   - `lib/searxng.ts` and `lib/groq.ts` indicate a two-stage backend pattern: live web search feeds model prompting, then Groq generates the structured output.
   - The README also mentions Gemini fallback, so AI generation is provider-aware rather than tied to one model.
   - Architecturally, this means the app is not just “LLM chat”; it combines external research with model synthesis.

7. **Team subsystem**
   - `app/(app)/team` is a separate interactive area for team analysis, prompts, workflow, tools, and role guides.
   - `app/(app)/team/TeamContext.tsx` shows shared state across that mini-product, while `components/team/*` provides a two-panel UI layout.
   - API routes like `team/analyze`, `team/generate-node`, `team/prompt`, and `team/role-guide` support this workflow.

8. **Persistence and backend data**
   - The repo contains `db/migrations.sql` plus routes for projects and streaks, so the app persists user/project progress and gamification state.
   - There are both Supabase and Firebase utility folders, which suggests the data/auth layer is either abstracted across providers or in transition.
   - In either case, the app has a clear backend state boundary for auth/session, project records, and progress tracking.

9. **Auth and session boundary**
   - Authentication is isolated in the `(auth)` route group and supported by `app/api/auth/callback` and `app/api/auth/session`.
   - `middleware.ts` and the Supabase middleware helpers indicate request-time protection of authenticated app routes.
   - This keeps public pages separate from the protected planning workspace.

10. **Shared UI and shell**
   - `components/Navbar.tsx`, `Sidebar.tsx`, `ActiveProjectList.tsx`, `StreakWidget.tsx`, and `TorusStreak.tsx` suggest a persistent product shell with navigation and progress feedback.
   - `components/ThemeProvider.tsx` and `ThemeToggle.tsx` handle global presentation state.
   - `components/ui.tsx` is the reusable design-system layer used across pages.

11. **Integration surfaces**
   - `app/api/mcp/route.ts` and `app/mcp/page.tsx` provide a Model Context Protocol surface, which is an external integration boundary for tooling/agent workflows.
   - Pages like `tools`, `portals`, `proposals`, and `master-prompt` expose curated outputs from the planning engine rather than raw editor functionality.

12. **Operational picture**
   - The app is designed for Vercel-style deployment with environment-based configuration.
   - External services materially affecting the architecture are: a hosted LLM provider, web search (SearXNG), and a hosted backend/auth/database service.
   - The runtime is a standard Next.js server/client split, with most business logic in API routes and lib helpers, and most orchestration surfaced through route-based UI flows.

Main entry points: [`app/(app)/planner/page.tsx`](https://github.com/bvs2006/torusai/blob/main/app/(app)/planner/page.tsx) (Planner), [`app/api/ai`](https://github.com/bvs2006/torusai/tree/main/app/api/ai) (AI API), [`app/api/projects`](https://github.com/bvs2006/torusai/tree/main/app/api/projects) (Projects API), [`app/(app)/team/page.tsx`](https://github.com/bvs2006/torusai/blob/main/app/(app)/team/page.tsx) (Team)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App routes"]
  node_n_home(("Home<br/>public entry<br/>[page.tsx]"))
  node_n_landing["Landing<br/>marketing page<br/>[page.tsx]"]
  node_n_auth["Auth"]
  node_n_workspace["Workspace<br/>authenticated shell<br/>[page.tsx]"]
  node_n_planner["Planner<br/>planning flow<br/>[page.tsx]"]
  node_n_architecture["Architecture<br/>planner stage<br/>[page.tsx]"]
  node_n_team["Team<br/>[page.tsx]"]
  node_n_tools["Tools<br/>generated outputs<br/>[page.tsx]"]
  node_n_portals["Portals<br/>output pages<br/>[page.tsx]"]
  node_n_master_prompt["Master prompt<br/>artifact page<br/>[page.tsx]"]
end

subgraph group_g_api["Server API"]
  node_n_api_ai["AI API<br/>ai orchestration"]
  node_n_api_team["Team API<br/>team orchestration"]
  node_n_api_projects[("Projects API<br/>project state")]
  node_n_api_streaks[("Streaks API<br/>progress tracking")]
  node_n_api_auth[("Auth API<br/>session boundary")]
  node_n_api_mcp(("MCP API<br/>integration surface"))
end

subgraph group_g_ui["Shared UI"]
  node_n_shell["Shell UI<br/>layout + nav"]
  node_n_team_ui["Team UI<br/>split-panel UI"]
end

subgraph group_g_core["Core logic"]
  node_n_ai_router{{"AI router<br/>provider routing<br/>[ai-router.ts]"}}
  node_n_search{{"Search<br/>[searxng.ts]"}}
  node_n_groq{{"Groq<br/>model client<br/>[groq.ts]"}}
end

subgraph group_g_data["Data layer"]
  node_n_supabase[("Supabase<br/>backend provider")]
  node_n_firebase[("Firebase<br/>alternate backend")]
  node_n_db["Schema<br/>migrations<br/>[migrations.sql]"]
end

node_n_home -->|"redirects to"| node_n_landing
node_n_home -->|"entry to auth"| node_n_auth
node_n_auth -->|"creates session"| node_n_api_auth
node_n_auth -->|"on success"| node_n_workspace
node_n_workspace -->|"uses shell"| node_n_shell
node_n_workspace -->|"launches"| node_n_planner
node_n_planner -->|"drills into"| node_n_architecture
node_n_planner -->|"surfaces"| node_n_tools
node_n_planner -->|"surfaces"| node_n_portals
node_n_planner -->|"generates"| node_n_master_prompt
node_n_planner -->|"requests AI"| node_n_api_ai
node_n_architecture -->|"step guidance"| node_n_api_ai
node_n_team -->|"uses"| node_n_team_ui
node_n_team -->|"requests team AI"| node_n_api_team
node_n_team -->|"reads project state"| node_n_api_projects
node_n_api_ai -->|"researches"| node_n_search
node_n_api_ai -->|"generates with"| node_n_groq
node_n_api_ai -->|"routes through"| node_n_ai_router
node_n_api_team -->|"routes through"| node_n_ai_router
node_n_api_projects -->|"persists to"| node_n_db
node_n_api_streaks -->|"tracks in"| node_n_db
node_n_api_auth -->|"uses"| node_n_supabase
node_n_api_projects -->|"uses"| node_n_supabase
node_n_api_team -.->|"may use"| node_n_firebase
node_n_api_mcp -->|"integrates with"| node_n_api_ai
node_n_shell -->|"shows progress"| node_n_api_streaks
node_n_shell -->|"lists projects"| node_n_api_projects

click node_n_home "https://github.com/bvs2006/torusai/blob/main/app/page.tsx"
click node_n_landing "https://github.com/bvs2006/torusai/blob/main/app/landing/page.tsx"
click node_n_auth "https://github.com/bvs2006/torusai/tree/main/app/(auth)"
click node_n_workspace "https://github.com/bvs2006/torusai/blob/main/app/workspace/page.tsx"
click node_n_planner "https://github.com/bvs2006/torusai/blob/main/app/(app)/planner/page.tsx"
click node_n_architecture "https://github.com/bvs2006/torusai/blob/main/app/(app)/planner/architecture/page.tsx"
click node_n_team "https://github.com/bvs2006/torusai/blob/main/app/(app)/team/page.tsx"
click node_n_tools "https://github.com/bvs2006/torusai/blob/main/app/tools/page.tsx"
click node_n_portals "https://github.com/bvs2006/torusai/blob/main/app/(app)/portals/page.tsx"
click node_n_master_prompt "https://github.com/bvs2006/torusai/blob/main/app/(app)/master-prompt/page.tsx"
click node_n_api_ai "https://github.com/bvs2006/torusai/tree/main/app/api/ai"
click node_n_api_team "https://github.com/bvs2006/torusai/tree/main/app/api/team"
click node_n_api_projects "https://github.com/bvs2006/torusai/tree/main/app/api/projects"
click node_n_api_streaks "https://github.com/bvs2006/torusai/tree/main/app/api/streaks"
click node_n_api_auth "https://github.com/bvs2006/torusai/tree/main/app/api/auth"
click node_n_api_mcp "https://github.com/bvs2006/torusai/tree/main/app/api/mcp"
click node_n_shell "https://github.com/bvs2006/torusai/tree/main/components"
click node_n_team_ui "https://github.com/bvs2006/torusai/tree/main/components/team"
click node_n_ai_router "https://github.com/bvs2006/torusai/blob/main/lib/ai-router.ts"
click node_n_search "https://github.com/bvs2006/torusai/blob/main/lib/searxng.ts"
click node_n_groq "https://github.com/bvs2006/torusai/blob/main/lib/groq.ts"
click node_n_supabase "https://github.com/bvs2006/torusai/tree/main/utils/supabase"
click node_n_firebase "https://github.com/bvs2006/torusai/tree/main/utils/firebase"
click node_n_db "https://github.com/bvs2006/torusai/blob/main/db/migrations.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_home,node_n_landing,node_n_auth,node_n_workspace,node_n_planner,node_n_architecture,node_n_team,node_n_tools,node_n_portals,node_n_master_prompt toneBlue
class node_n_api_ai,node_n_api_team,node_n_api_projects,node_n_api_streaks,node_n_api_auth,node_n_api_mcp toneAmber
class node_n_shell,node_n_team_ui toneMint
class node_n_ai_router,node_n_search,node_n_groq toneRose
class node_n_supabase,node_n_firebase,node_n_db toneIndigo
```

## Components

### App routes

Next.js App Router entrypoints and protected product surfaces.

- [Home](https://github.com/bvs2006/torusai/blob/main/app/page.tsx): public entry · Public landing entry for the app. · `app/page.tsx`
- [Landing](https://github.com/bvs2006/torusai/blob/main/app/landing/page.tsx): marketing page · Public marketing/landing experience. · `app/landing/page.tsx`
- [Auth](https://github.com/bvs2006/torusai/tree/main/app/(auth)): auth routes · Login, signup, and password recovery surface. · `app/(auth)`
- [Workspace](https://github.com/bvs2006/torusai/blob/main/app/workspace/page.tsx): authenticated shell · Primary post-login shell with onboarding and dashboard entry points. · `app/workspace/page.tsx`
- [Planner](https://github.com/bvs2006/torusai/blob/main/app/(app)/planner/page.tsx): planning flow · Main guided workflow for turning ideas into plans. · `app/(app)/planner/page.tsx`
- [Architecture](https://github.com/bvs2006/torusai/blob/main/app/(app)/planner/architecture/page.tsx): planner stage · Architecture planning and drill-down views. · `app/(app)/planner/architecture/page.tsx`
- [Team](https://github.com/bvs2006/torusai/blob/main/app/(app)/team/page.tsx): team workspace · Interactive team-analysis and role guidance area. · `app/(app)/team/page.tsx`
- [Tools](https://github.com/bvs2006/torusai/blob/main/app/tools/page.tsx): generated outputs · Curated tool recommendations and related outputs. · `app/tools/page.tsx`
- [Portals](https://github.com/bvs2006/torusai/blob/main/app/(app)/portals/page.tsx): output pages · Planning artifacts surfaced as dedicated pages. · `app/(app)/portals/page.tsx`
- [Master prompt](https://github.com/bvs2006/torusai/blob/main/app/(app)/master-prompt/page.tsx): artifact page · Generated prompt assembly surface for downstream use. · `app/(app)/master-prompt/page.tsx`

### Server API

Route handlers that orchestrate AI, auth, projects, and progress.

- [AI API](https://github.com/bvs2006/torusai/tree/main/app/api/ai): ai orchestration · Server boundary for planning, prompting, validation, and tool synthesis. · `app/api/ai`
- [Team API](https://github.com/bvs2006/torusai/tree/main/app/api/team): team orchestration · Server boundary for team analysis, prompts, and role guidance. · `app/api/team`
- [Projects API](https://github.com/bvs2006/torusai/tree/main/app/api/projects): project state · CRUD boundary for persisted project records. · `app/api/projects`
- [Streaks API](https://github.com/bvs2006/torusai/tree/main/app/api/streaks): progress tracking · Gamification and activity tracking endpoints. · `app/api/streaks`
- [Auth API](https://github.com/bvs2006/torusai/tree/main/app/api/auth): session boundary · Auth callback and session endpoints. · `app/api/auth`
- [MCP API](https://github.com/bvs2006/torusai/tree/main/app/api/mcp): integration surface · Model Context Protocol endpoint for external tool workflows. · `app/api/mcp`

### Shared UI

Reusable shell, layout, and product widgets.

- [Shell UI](https://github.com/bvs2006/torusai/tree/main/components): layout + nav · Persistent product chrome: navigation, sidebar, theme, and streak widgets. · `components`
- [Team UI](https://github.com/bvs2006/torusai/tree/main/components/team): split-panel UI · Two-panel team workspace components and shared context. · `components/team`

### Core logic

Provider, search, and state helpers used by the app and APIs.

- [AI router](https://github.com/bvs2006/torusai/blob/main/lib/ai-router.ts): provider routing · Chooses between model/providers and shapes AI requests. · `lib/ai-router.ts`
- [Search](https://github.com/bvs2006/torusai/blob/main/lib/searxng.ts): web research · SearXNG-backed live research used before generation. · `lib/searxng.ts`
- [Groq](https://github.com/bvs2006/torusai/blob/main/lib/groq.ts): model client · Primary LLM client for structured generation. · `lib/groq.ts`

### Data layer

Persistence and provider-specific integration utilities.

- [Supabase](https://github.com/bvs2006/torusai/tree/main/utils/supabase): backend provider · Auth/session and app data provider boundary. · `utils/supabase`
- [Firebase](https://github.com/bvs2006/torusai/tree/main/utils/firebase): alternate backend · Secondary provider utilities for auth/data/team helpers. · `utils/firebase`
- [Schema](https://github.com/bvs2006/torusai/blob/main/db/migrations.sql): migrations · Database migration and persistence schema definitions. · `db/migrations.sql`

## Connections

- Home → Landing: redirects to · Public entry routes users into the marketing surface.
- Home → Auth: entry to auth · Unauthenticated users move into login/signup flows.
- Auth → Auth API: creates session · Auth pages rely on callback and session endpoints.
- Auth → Workspace: on success · Successful sign-in transitions into the product shell.
- Workspace → Shell UI: uses shell · Authenticated surfaces share persistent navigation and widgets.
- Workspace → Planner: launches · Workspace funnels users into the planning workflow.
- Planner → Architecture: drills into · Planner branches into architecture guidance and drill-down pages.
- Planner → Tools: surfaces · Planner emits tool recommendations and related artifacts.
- Planner → Portals: surfaces · Planner exposes downstream artifact pages.
- Planner → Master prompt: generates · Planner can produce a master prompt artifact.
- Planner → AI API: requests AI · Main workflow delegates generation and validation to AI routes.
- Architecture → AI API: step guidance · Architecture guides use AI-backed step and role endpoints.
- Team → Team UI: uses · Team workspace is built around a shared split-panel layout.
- Team → Team API: requests team AI · Team flows call dedicated team orchestration endpoints.
- Team → Projects API: reads project state · Team context is coupled to persisted project data.
- AI API → Search: researches · AI routes can fetch live web context before generation.
- AI API → Groq: generates with · Model synthesis is performed through the Groq client.
- AI API → AI router: routes through · Provider selection and fallback are centralized here.
- Team API → AI router: routes through · Team generation also uses provider-aware orchestration.
- Projects API → Schema: persists to · Project records are backed by the database schema.
- Streaks API → Schema: tracks in · Progress and streak data are persisted in storage.
- Auth API → Supabase: uses · Auth/session handling is mediated by Supabase utilities.
- Projects API → Supabase: uses · Project state APIs depend on the backend provider layer.
- Team API → Firebase: may use · Team utilities include Firebase-based integration support.
- MCP API → AI API: integrates with · External MCP surface exposes planning capabilities to tools.
- Shell UI → Streaks API: shows progress · Streak widgets and badges display tracked user activity.
- Shell UI → Projects API: lists projects · Sidebar and project lists are fed by persisted project state.