# sowmya-kolli/forge-execution-intelligence architecture

> Architecture diagram of the GitHub repository sowmya-kolli/forge-execution-intelligence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sowmya-kolli/forge-execution-intelligence
- Repository: https://github.com/sowmya-kolli/forge-execution-intelligence

## Overview

1. **High-level shape**
   - FORGE is a **Next.js App Router frontend** backed by **Supabase** for authentication and user data.
   - The repo is organized around one core product flow: **landing → auth → planner/focus/analytics/settings/structure**.
   - There is no standalone API server in this repository; the app delegates auth and persistence to Supabase and uses client-side state for fast interaction.

2. **Route-level architecture**
   - The `app/` directory defines the top-level shell and route pages.
   - Feature pages live under `app/app/` for:
     - `planner`
     - `focus`
     - `analytics`
     - `settings`
     - `structure`
   - This suggests a split between a public entry experience and the authenticated product surface.

3. **Public vs authenticated surfaces**
   - `app/page.js` is the entry/landing experience.
   - `components/Auth/AuthGuard.js` and `components/Auth/AuthModal.js` indicate that authenticated routes are protected and login can be triggered from inside the UI.
   - `context/AuthContext.js` likely centralizes session state so route components can tell whether the user is signed in and whether profile data is available.

4. **Authentication and data access boundary**
   - `lib/supabase.js` is the integration point for Supabase client setup.
   - The README describes **email-based Supabase Auth** and **RLS-protected per-user data**, so the architectural boundary is:  
     **UI + local state in the browser** → **Supabase Auth/session** → **Supabase tables (`profiles`, `tasks`)**.
   - Email templates under `email-templates/` support the auth flow, including signup confirmation.

5. **Planner subsystem**
   - The planner is the “Structure” side of the product: task creation, classification, and scheduling.
   - The README describes tasks as only **pending** or **completed**, with metadata like **priority**, **energy**, and **duration**.
   - This maps to a task model likely stored in Supabase and rendered in the planner page as a living calendar / weekly execution board.

6. **Focus protocol subsystem**
   - `components/Focus/` contains a staged flow for deep work:
     - `EntryOverlay`
     - `EntryRitual`
     - `TaskLockIn`
     - `DeepFocus`
     - `CompletionEffect`
     - `ExitSummary`
   - These components imply a **multi-step session state machine** rather than a single timer screen.
   - `store/useFocusStore.js` is the likely local source of truth for the active focus session, timer/intensity, and transition between stages.

7. **Local state and persistence**
   - Zustand is the core client-side state layer, especially for focus sessions.
   - The README explicitly calls out **Zustand persistence**, which means some user experience state survives reloads locally.
   - This is important architecturally because focus interactions need to feel instant and resilient even before data sync or analytics writes happen.

8. **Analytics and progression**
   - The `analytics` page is where the app turns execution history into feedback.
   - The README describes a **heatmap**, **XP/levels/badges**, and **streak tracking**, so analytics is not just reporting—it is a progression system.
   - This subsystem likely consumes aggregated focus/task completion data, whether from Supabase records or locally persisted session history.

9. **Settings and reset semantics**
   - `app/app/settings/page.js` supports user preferences and account-related controls.
   - The README mentions a **factory reset** and local storage wipe on logout, which indicates settings is also where the app exposes state hygiene and account lifecycle actions.
   - This is a meaningful architectural boundary: some data is server-backed, while some UX state is intentionally local and erasable.

10. **Structure / onboarding / product guidance**
   - `app/app/structure/page.js` and `components/Onboarding/OnboardingTour.js` suggest an explanatory layer that teaches the “Forge” methodology.
   - This is consistent with the product being opinionated: it is not just task management, but a guided execution system.
   - The onboarding layer likely connects landing onboarding to the first planner or focus session.

11. **Shared UI and layout system**
   - `components/Layout/Sidebar.js` is the main navigation shell for the authenticated app.
   - `components/UI/Card.js` and `components/UI/InfoTooltip.js` are reusable primitives used across planner, analytics, and settings.
   - Styling is handled by **Tailwind CSS** plus globals in `app/globals.css`, so the visual system is component-driven rather than stylesheet-heavy.

12. **Landing and marketing experience**
   - `components/Landing/` contains the most visually complex pieces:
     - `HeroParallax`
     - `ThreeDCarousel`
     - `CardSpace3D`
     - `TiltCard`
   - These components indicate a distinct public-facing experience optimized for storytelling and conversion before the user enters the app.

13. **Operational flow of the app**
   - A typical data flow is:
     1. user lands on the public page,
     2. authenticates via Supabase,
     3. AuthContext stores session/profile state,
     4. AuthGuard opens the protected app,
     5. planner/focus pages read or write user-specific data,
     6. analytics summarizes completed work and streaks.
   - Focus sessions mostly run locally in the browser during execution, then contribute to longer-term metrics.

14. **Key architectural takeaway for a diagram**
   - The repo is best drawn as a **client-heavy Next.js application** with three major state domains:
     - **auth/session state** via Supabase,
     - **persistent task/progress data** via Supabase tables and RLS,
     - **ephemeral focus-session state** via Zustand and local persistence.
   - The product experience is organized around a strict execution workflow, not around generic CRUD pages.

Main entry points: [`app/app/layout.js`](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/layout.js) (App Layout), [`lib/supabase.js`](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/lib/supabase.js) (Supabase), [`app/page.js`](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/page.js) (Landing), [`app/app/settings/page.js`](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/settings/page.js) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public"]
  node_landing["Landing<br/>public entry<br/>[page.js]"]
  node_landing_fx["Landing FX<br/>visual storytelling<br/>[HeroParallax.js]"]
end

subgraph group_appshell["App Shell"]
  node_root["Next.js App<br/>framework shell<br/>[layout.js]"]
  node_app_layout["App Layout<br/>route shell<br/>[layout.js]"]
  node_planner["Planner<br/>task board<br/>[page.js]"]
  node_analytics["Analytics<br/>progress view<br/>[page.js]"]
  node_settings["Settings<br/>preferences<br/>[page.js]"]
  node_structure["Structure<br/>guidance page<br/>[page.js]"]
end

subgraph group_focussys["Focus System"]
  node_focus["Focus<br/>session flow<br/>[page.js]"]
  node_focus_store[("Focus Store<br/>local state<br/>[useFocusStore.js]")]
  node_entry_overlay["Entry Overlay<br/>focus stage<br/>[EntryOverlay.js]"]
  node_entry_ritual["Entry Ritual<br/>focus stage<br/>[EntryRitual.js]"]
  node_task_lockin["Task Lock-in<br/>focus stage<br/>[TaskLockIn.js]"]
  node_deep_focus["Deep Focus<br/>focus stage<br/>[DeepFocus.js]"]
  node_completion["Completion<br/>focus stage"]
  node_exit_summary["Exit Summary<br/>focus stage<br/>[ExitSummary.js]"]
end

subgraph group_data["Data Boundary"]
  node_auth_guard["Auth Guard<br/>route protection<br/>[AuthGuard.js]"]
  node_auth_modal["Auth Modal<br/>login UI<br/>[AuthModal.js]"]
  node_auth_context[("Auth Context<br/>session state<br/>[AuthContext.js]")]
  node_supabase[("Supabase<br/>backend service<br/>[supabase.js]")]
end

subgraph group_shared["Shared UI"]
  node_sidebar["Sidebar<br/>nav shell<br/>[Sidebar.js]"]
  node_onboarding["Onboarding Tour<br/>guided tour<br/>[OnboardingTour.js]"]
  node_ui_cards["UI Primitives<br/>shared components<br/>[Card.js]"]
end

node_root -->|"public route"| node_landing
node_root -->|"app shell"| node_app_layout
node_app_layout -->|"navigation"| node_sidebar
node_app_layout -->|"protects"| node_auth_guard
node_auth_guard -->|"reads session"| node_auth_context
node_auth_context -->|"session sync"| node_supabase
node_auth_guard -->|"opens login"| node_auth_modal
node_landing -->|"storytelling"| node_landing_fx
node_landing -->|"sign in"| node_auth_modal
node_app_layout -->|"route"| node_planner
node_app_layout -->|"route"| node_focus
node_app_layout -->|"route"| node_analytics
node_app_layout -->|"route"| node_settings
node_app_layout -->|"route"| node_structure
node_structure -->|"guides"| node_onboarding
node_planner -->|"tasks data"| node_supabase
node_focus -->|"local flow"| node_focus_store
node_focus -->|"stage"| node_entry_overlay
node_entry_overlay -->|"advances"| node_entry_ritual
node_entry_ritual -->|"advances"| node_task_lockin
node_task_lockin -->|"starts"| node_deep_focus
node_deep_focus -->|"finishes"| node_completion
node_completion -->|"wraps up"| node_exit_summary
node_analytics -->|"progress data"| node_supabase
node_settings -->|"account data"| node_supabase
node_settings -->|"reset local"| node_focus_store
node_ui_cards -->|"shared ui"| node_planner
node_ui_cards -->|"shared ui"| node_analytics

click node_root "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/layout.js"
click node_landing "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/page.js"
click node_app_layout "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/layout.js"
click node_sidebar "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Layout/Sidebar.js"
click node_auth_guard "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Auth/AuthGuard.js"
click node_auth_modal "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Auth/AuthModal.js"
click node_auth_context "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/context/AuthContext.js"
click node_supabase "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/lib/supabase.js"
click node_planner "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/planner/page.js"
click node_focus "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/focus/page.js"
click node_focus_store "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/store/useFocusStore.js"
click node_entry_overlay "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/EntryOverlay.js"
click node_entry_ritual "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/EntryRitual.js"
click node_task_lockin "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/TaskLockIn.js"
click node_deep_focus "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/DeepFocus.js"
click node_completion "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/CompletionEffect.js"
click node_exit_summary "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/ExitSummary.js"
click node_analytics "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/analytics/page.js"
click node_settings "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/settings/page.js"
click node_structure "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/structure/page.js"
click node_onboarding "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Onboarding/OnboardingTour.js"
click node_ui_cards "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/UI/Card.js"
click node_landing_fx "https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Landing/HeroParallax.js"

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_landing,node_landing_fx toneBlue
class node_root,node_app_layout,node_planner,node_analytics,node_settings,node_structure toneAmber
class node_focus,node_focus_store,node_entry_overlay,node_entry_ritual,node_task_lockin,node_deep_focus,node_completion,node_exit_summary toneMint
class node_auth_guard,node_auth_modal,node_auth_context,node_supabase toneRose
class node_sidebar,node_onboarding,node_ui_cards toneIndigo
```

## Components

### Public

Landing and signup entry experience

- [Landing](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/page.js): public entry · Marketing and first-contact experience · `app/page.js`
- [Landing FX](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Landing/HeroParallax.js): visual storytelling · 3D and parallax landing components · `components/Landing/HeroParallax.js`

### App Shell

Authenticated product routes and shared navigation

- [Next.js App](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/layout.js): framework shell · App Router application entry and route composition · `app/layout.js`
- [App Layout](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/layout.js): route shell · Authenticated route layout and navigation scaffold · `app/app/layout.js`
- [Planner](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/planner/page.js): task board · Task structure and scheduling workspace · `app/app/planner/page.js`
- [Analytics](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/analytics/page.js): progress view · Heatmaps, streaks, XP, and badges · `app/app/analytics/page.js`
- [Settings](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/settings/page.js): preferences · User controls, reset, and account hygiene · `app/app/settings/page.js`
- [Structure](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/structure/page.js): guidance page · Methodology and onboarding-oriented guidance · `app/app/structure/page.js`

### Focus System

Multi-step deep-work session flow

- [Focus](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/app/app/focus/page.js): session flow · Deep work execution surface · `app/app/focus/page.js`
- [Focus Store](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/store/useFocusStore.js): local state · Persistent client state for active focus sessions · `store/useFocusStore.js`
- [Entry Overlay](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/EntryOverlay.js): focus stage · Initial focus session entry step · `components/Focus/EntryOverlay.js`
- [Entry Ritual](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/EntryRitual.js): focus stage · Pre-focus transition and readiness step · `components/Focus/EntryRitual.js`
- [Task Lock-in](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/TaskLockIn.js): focus stage · Selects and commits the active task · `components/Focus/TaskLockIn.js`
- [Deep Focus](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/DeepFocus.js): focus stage · Main timed concentration session · `components/Focus/DeepFocus.js`
- [Completion](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/CompletionEffect.js): focus stage · Success feedback and wrap-up effects · `components/Focus/CompletionEffect.js`
- [Exit Summary](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Focus/ExitSummary.js): focus stage · Session recap and closure state · `components/Focus/ExitSummary.js`

### Data Boundary

Auth, session, and persistence integration

- [Auth Guard](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Auth/AuthGuard.js): route protection · Protects authenticated surfaces and gates access · `components/Auth/AuthGuard.js`
- [Auth Modal](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Auth/AuthModal.js): login UI · In-app sign-in and session entry modal · `components/Auth/AuthModal.js`
- [Auth Context](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/context/AuthContext.js): session state · Centralized client session and profile state · `context/AuthContext.js`
- [Supabase](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/lib/supabase.js): backend service · Auth and per-user data persistence boundary · `lib/supabase.js`

### Shared UI

Reusable components and onboarding

- [Sidebar](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Layout/Sidebar.js): nav shell · Primary navigation for the protected app · `components/Layout/Sidebar.js`
- [Onboarding Tour](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/Onboarding/OnboardingTour.js): guided tour · Explains the workflow and product method · `components/Onboarding/OnboardingTour.js`
- [UI Primitives](https://github.com/sowmya-kolli/forge-execution-intelligence/blob/main/components/UI/Card.js): shared components · Reusable cards and tooltips across the app · `components/UI/Card.js`

## Connections

- Next.js App → Landing: public route · Top-level entry renders landing experience
- Next.js App → App Layout: app shell · Authenticated routes mount under the app layout
- App Layout → Sidebar: navigation · Layout provides the primary sidebar shell
- App Layout → Auth Guard: protects · Authenticated surface is gated by auth checks
- Auth Guard → Auth Context: reads session · Guard uses session/profile state to decide access
- Auth Context → Supabase: session sync · Context is backed by Supabase auth
- Auth Guard → Auth Modal: opens login · Unauthorized users can sign in from the UI
- Landing → Landing FX: storytelling · Landing uses rich visual components for conversion
- Landing → Auth Modal: sign in · Public surface can trigger login entry
- App Layout → Planner: route · Planner is a primary authenticated workspace
- App Layout → Focus: route · Focus session workspace is part of the app surface
- App Layout → Analytics: route · Analytics summarizes progress for signed-in users
- App Layout → Settings: route · Settings manages preferences and reset actions
- App Layout → Structure: route · Structure page explains the product method
- Structure → Onboarding Tour: guides · Structure content connects to the onboarding tour
- Planner → Supabase: tasks data · Planner reads and writes user-specific task records
- Focus → Focus Store: local flow · Focus page runs on persistent client session state
- Focus → Entry Overlay: stage · Session begins with entry overlay
- Entry Overlay → Entry Ritual: advances · First stage transitions into ritual
- Entry Ritual → Task Lock-in: advances · Ritual leads into task selection
- Task Lock-in → Deep Focus: starts · Locked task enters the main focus session
- Deep Focus → Completion: finishes · Completed focus work triggers feedback effects
- Completion → Exit Summary: wraps up · Completion ends with a summary state
- Analytics → Supabase: progress data · Analytics consumes persisted execution history
- Settings → Supabase: account data · Settings interacts with authenticated user data
- Settings → Focus Store: reset local · Factory reset and logout can clear local persisted state
- UI Primitives → Planner: shared ui · Reusable primitives support planner screens
- UI Primitives → Analytics: shared ui · Reusable primitives support analytics screens
