How sowmya-kolli/forge-execution-intelligence works
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: layout.js App Layout · supabase.js Supabase · app/page.js Landing · settings/page.js Settings
Components 23
Public
Landing and signup entry experience
- Landing · Marketing and first-contact experience
app/page.js - Landing FX · 3D and parallax landing components
components/Landing/HeroParallax.js
App Shell
Authenticated product routes and shared navigation
- Next.js App · App Router application entry and route composition
app/layout.js - App Layout · Authenticated route layout and navigation scaffold
app/app/layout.js - Planner · Task structure and scheduling workspace
app/app/planner/page.js - Analytics · Heatmaps, streaks, XP, and badges
app/app/analytics/page.js - Settings · User controls, reset, and account hygiene
app/app/settings/page.js - Structure · Methodology and onboarding-oriented guidance
app/app/structure/page.js
Focus System
Multi-step deep-work session flow
- Focus · Deep work execution surface
app/app/focus/page.js - Focus Store · Persistent client state for active focus sessions
store/useFocusStore.js - Entry Overlay · Initial focus session entry step
components/Focus/EntryOverlay.js - Entry Ritual · Pre-focus transition and readiness step
components/Focus/EntryRitual.js - Task Lock-in · Selects and commits the active task
components/Focus/TaskLockIn.js - Deep Focus · Main timed concentration session
components/Focus/DeepFocus.js - Completion · Success feedback and wrap-up effects
components/Focus/CompletionEffect.js - Exit Summary · Session recap and closure state
components/Focus/ExitSummary.js
Data Boundary
Auth, session, and persistence integration
- Auth Guard · Protects authenticated surfaces and gates access
components/Auth/AuthGuard.js - Auth Modal · In-app sign-in and session entry modal
components/Auth/AuthModal.js - Auth Context · Centralized client session and profile state
context/AuthContext.js - Supabase · Auth and per-user data persistence boundary
lib/supabase.js
Shared UI
Reusable components and onboarding
- Sidebar · Primary navigation for the protected app
components/Layout/Sidebar.js - Onboarding Tour · Explains the workflow and product method
components/Onboarding/OnboardingTour.js - UI Primitives · Reusable cards and tooltips across the app
components/UI/Card.js
Connections 28
- 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