How bvs2006/torusai works
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: planner/page.tsx Planner · ai AI API · projects Projects API · team/page.tsx Team
Components 24
App routes
Next.js App Router entrypoints and protected product surfaces.
- Home · Public landing entry for the app.
app/page.tsx - Landing · Public marketing/landing experience.
app/landing/page.tsx - Auth · Login, signup, and password recovery surface.
app/(auth) - Workspace · Primary post-login shell with onboarding and dashboard entry points.
app/workspace/page.tsx - Planner · Main guided workflow for turning ideas into plans.
app/(app)/planner/page.tsx - Architecture · Architecture planning and drill-down views.
app/(app)/planner/architecture/page.tsx - Team · Interactive team-analysis and role guidance area.
app/(app)/team/page.tsx - Tools · Curated tool recommendations and related outputs.
app/tools/page.tsx - Portals · Planning artifacts surfaced as dedicated pages.
app/(app)/portals/page.tsx - Master prompt · 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 · Server boundary for planning, prompting, validation, and tool synthesis.
app/api/ai - Team API · Server boundary for team analysis, prompts, and role guidance.
app/api/team - Projects API · CRUD boundary for persisted project records.
app/api/projects - Streaks API · Gamification and activity tracking endpoints.
app/api/streaks - Auth API · Auth callback and session endpoints.
app/api/auth - MCP API · Model Context Protocol endpoint for external tool workflows.
app/api/mcp
Shared UI
Reusable shell, layout, and product widgets.
Core logic
Provider, search, and state helpers used by the app and APIs.
Connections 27
- 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.