CORTEX — Phased Implementation Plan

AI-Powered Code Editor | Based on Cortex_PRD_v1.0.md

CURRENT IMPLEMENTATION BASELINE — First Commit Layout Shell

As of May 22, 2026, only the first scaffold and layout milestone should be treated as verified. Later phase checkboxes in this historical plan must be revalidated before they are considered complete.

⚠️ INSTRUCTIONS FOR THE EXECUTING AI

Before starting ANY phase, re-read Cortex_PRD_v1.0.md in its entirety to understand the full context.
Complete tasks in order — each phase builds on the previous one.
After completing each task, mark it [x] in this file before moving to the next.
After completing an entire phase, mark the phase header [x] before starting the next phase.
Do not skip tasks — every task corresponds to a specific PRD requirement.
Technology decisions are locked — use exact versions specified in the PRD (Section 3).
Design tokens are non-negotiable — use ONLY the SCSS variables from PRD Section 4. No hardcoded CSS values.
Never use placeholder images or lorem ipsum — all UI must reflect the actual product.

TECH STACK REFERENCE (do not deviate)

Layer	Technology
Frontend	React 18.x + Vite, Monaco Editor 0.47.x, SCSS 1.70.x, Zustand 4.x, React Router v6, D3.js 7.x, Axios 1.6.x
Backend	Node.js 20 LTS, Express.js 4.x, MongoDB 7.x, Mongoose 8.x, Multer 1.4.x, Socket.IO 4.x
AI Provider	Google Gemini 2.0 Flash (`gemini-2.0-flash-exp`) via `@google/generative-ai` SDK, Groq as fallback
Auth	Clerk (JWT middleware on all backend routes)
DB	MongoDB Atlas (free M0)

FOLDER STRUCTURE REFERENCE

Frontend (client/src/):

components/     → Reusable atoms: Button, Modal, Badge, Tag, Tooltip
layouts/        → AppShell.jsx (3-panel layout)
features/
  intent/       → IntentMode.jsx, IntentSelector.jsx, IntentResultPanel.jsx, useIntentMode.js
  explainer/    → CodebaseExplainer.jsx, DependencyGraph.jsx, FlowOverlay.jsx, useExplainer.js
  memory/       → DecisionMemory.jsx, MemoryAnnotation.jsx, MemorySearch.jsx, useMemory.js
editor/         → MonacoWrapper.jsx, EditorTabs.jsx, FileTree.jsx, EditorToolbar.jsx
store/          → editorStore.js, projectStore.js, memoryStore.js, uiStore.js
api/            → intentApi.js, explainerApi.js, memoryApi.js
hooks/          → useProject.js, useSocket.js, useTheme.js, useDebounce.js
styles/         → _variables.scss, _reset.scss, _typography.scss, _utilities.scss, main.scss
styles/components/ → _button.scss, _tabs.scss, _sidebar.scss, _modal.scss
pages/          → Editor.jsx, MemoryVault.jsx, ExplainerView.jsx, Settings.jsx
utils/          → fileParser.js, tokenCounter.js, graphBuilder.js, diffHighlighter.js

Backend (server/):

index.js
routes/         → intent.routes.js, explainer.routes.js, memory.routes.js, project.routes.js
controllers/    → IntentController.js, ExplainerController.js, MemoryController.js
services/       → GeminiService.js, CodeParserService.js, GraphBuilderService.js
models/         → DecisionMemory.js, Project.js, CodebaseSnapshot.js
middleware/     → Auth.js, RateLimit.js, ErrorHandler.js, RequestLogger.js
utils/          → fileExtractor.js, promptBuilder.js, tokenEstimator.js
sockets/        → streamHandler.js, intentStream.js

PHASE 1 — Foundation & Project Setup

PRD Reference: Section 9 — Phase 1 (Week 1–2), Section 3 (Tech Stack), Section 4 (Design System), Section 7.1 (App Shell Layout) Goal: Initialize the full MERN project with Vite, configure auth with Clerk, build the SCSS design system, Monaco Editor wrapper, and the 3-panel App Shell.

1.1 — Project Initialization

1.1.1 Create root project folder cortex/ with two subdirectories: client/ (Vite+React) and server/ (Express).
1.1.2 Initialize client/ using Vite: npm create vite@latest client -- --template react. Install dependencies: react-router-dom@6, zustand@4, axios@1.6, monaco-editor@0.47, @monaco-editor/react, sass@1.70, socket.io-client@4, @clerk/clerk-react.
1.1.3 Initialize server/ with npm init -y. Install: express@4, mongoose@8, multer@1.4, socket.io@4, dotenv@16, cors, @clerk/clerk-sdk-node, @google/generative-ai, groq-sdk.
1.1.4 Create server/.env with placeholders for all environment variables from PRD Section 10.1: GEMINI_API_KEY, GROQ_API_KEY, MONGODB_URI, CLERK_SECRET_KEY, VITE_CLERK_PUBLISHABLE_KEY, PORT=3001, CLIENT_URL=http://localhost:5173.
1.1.5 Create client/.env with VITE_CLERK_PUBLISHABLE_KEY and VITE_API_URL=http://localhost:3001.
1.1.6 Configure vite.config.js to proxy /api to http://localhost:3001.
1.1.7 Create root package.json with dev script running both client and server concurrently (use concurrently npm package).

1.2 — SCSS Design System

Re-read PRD Section 4 (Design System) before starting this section.

1.3 — Base UI Components

Re-read PRD Section 4.7 (Component Design Patterns) before starting.

1.3.1 Create client/src/components/Button/Button.jsx and _button.scss. Implement three variants: primary, ghost, icon as specified in PRD Section 4.7. All styles use SCSS tokens only.
1.3.2 Create client/src/components/Badge/Badge.jsx and its SCSS. Badge variants: success, warning, error, primary, secondary. Uses $radius-sm, appropriate $color-* tokens.
1.3.3 Create client/src/components/Tag/Tag.jsx and its SCSS. Closeable tag component for memory tags. Style with $color-bg-elevated, $radius-sm.
1.3.4 Create client/src/components/Modal/Modal.jsx and _modal.scss. Implements a centered overlay modal with backdrop blur. Uses $color-bg-surface, $shadow-lg, $radius-lg.
1.3.5 Create client/src/components/Tooltip/Tooltip.jsx — hover tooltip. Uses $color-bg-elevated, $shadow-md, $font-size-xs.
1.3.6 Create client/src/components/Spinner/Spinner.jsx — animated loading spinner using $color-primary.
1.3.7 Create client/src/components/Skeleton/Skeleton.jsx — skeleton loader component with shimmer animation using $color-bg-elevated to $color-bg-surface gradient.

1.4 — Zustand Store Setup

1.4.1 Create client/src/store/editorStore.js — Zustand slice managing: openFiles[], activeFileId, tabOrder[], editorContent (map of fileId → content).
1.4.2 Create client/src/store/projectStore.js — managing: projects[], activeProjectId, projectFiles (file tree structure).
1.4.3 Create client/src/store/memoryStore.js — managing: memories[], activeMemoryId, isMemoryPanelOpen.
1.4.4 Create client/src/store/uiStore.js — managing: sidebarWidth, featurePanelOpen, featurePanelMode (intent | explainer | memory), bottomPanelOpen, bottomPanelHeight.

1.5 — App Shell Layout

Re-read PRD Section 7.1 (App Shell Layout) before starting.

1.5.1 Create client/src/layouts/AppShell.jsx — the 3-panel IDE layout. Renders: ActivityBar (48px fixed left), Sidebar (240px resizable), Editor Area (flex fill), Feature Panel (380px resizable right), Bottom Panel (200px collapsible). Use CSS Grid or Flexbox layout.
1.5.2 Create client/src/styles/components/_sidebar.scss — Sidebar panel styles using $color-bg-surface. File tree indent is 16px per level, active file uses $color-primary-muted background and $color-primary-hover text.
1.5.3 Create client/src/editor/EditorToolbar.jsx — the toolbar between tab strip and Monaco. Five zones as per PRD Section 7.2: Breadcrumb, Language badge + line:col, Three Feature CTA buttons (Intent Mode=violet, Explain Codebase=cyan, Add Memory=amber), format/wordwrap/minimap toggles, Settings gear + User avatar.
1.5.4 Style the Activity Bar — 48px wide, $color-bg-surface background, icon nav for File Tree, Search, Memory Vault, Settings, User Avatar icons. Active icon highlighted with $color-primary.
1.5.5 Create client/src/editor/EditorTabs.jsx — horizontal tab strip. Active tab: $color-primary bottom border (2px), $color-text-primary text. Inactive: $color-bg-surface, $color-text-secondary. Close icon appears on hover. Horizontally scrollable when > 8 tabs.
1.5.6 Implement panel resizing for Sidebar (min 160px, max 400px) and Feature Panel (min 300px, max 600px) using drag handles. Persist widths to uiStore.

1.6 — MongoDB & Backend Foundation

1.6.1 Create server/index.js — Express app setup: CORS (whitelist CLIENT_URL), JSON body parser, Multer setup, Socket.IO attached to HTTP server, connect to MongoDB Atlas via Mongoose.
1.6.2 Create server/middleware/Auth.js — Clerk JWT verification middleware. Extracts Bearer token, verifies with @clerk/clerk-sdk-node, attaches userId to req.
1.6.3 Create server/middleware/ErrorHandler.js — global Express error handler. Returns { error: message, code } JSON. Handles Mongoose validation errors and Gemini API errors distinctly.
1.6.4 Create server/middleware/RequestLogger.js — logs method + path + status + duration for every request.
1.6.5 Create server/models/Project.js — Mongoose schema: { clerkUserId: String, name: String, description: String, fileTree: Object, createdAt: Date, updatedAt: Date }. Add index on { clerkUserId: 1 }.
1.6.6 Create server/routes/project.routes.js with CRUD endpoints: POST /api/projects, GET /api/projects (user's projects), GET /api/projects/:id, PATCH /api/projects/:id, DELETE /api/projects/:id. All routes use Auth.js middleware.
1.6.7 Create server/controllers/ProjectController.js — business logic for all project endpoints.

1.7 — Monaco Editor Integration

1.7.1 Create client/src/editor/MonacoWrapper.jsx — wraps @monaco-editor/react. Configure Monaco theme using Cortex design tokens: background = $color-code-bg (#0D0D17), selection = $color-highlight (#4F6EF720), font = $font-mono. Enable IntelliSense, multi-cursor, minimap.
1.7.2 Implement file tree in client/src/editor/FileTree.jsx — renders project file tree from projectStore. Folders with chevron expand/collapse. 16px indent per level. Active file highlighted. Right-click context menu: rename, delete, "Add Decision Memory", "Copy Path".
1.7.3 Create client/src/hooks/useProject.js — hook for loading project, switching active file, and syncing file content with editorStore.
1.7.4 Wire up routing in client/src/main.jsx using React Router v6: / → Editor page, /memory → MemoryVault page, /explainer → ExplainerView page, /settings → Settings page.
1.7.5 Create client/src/pages/Editor.jsx — renders AppShell with MonacoWrapper + FileTree + EditorTabs + EditorToolbar.

1.8 — Clerk Auth Integration

1.8.1 Wrap client/src/main.jsx with <ClerkProvider publishableKey={...}>. Add <SignedIn> / <SignedOut> guards so only authenticated users see the Editor.
1.8.2 Create a LandingPage.jsx or AuthPage.jsx rendered when signed out — shows Cortex logo, tagline "Code with Intent. Build with Memory.", and Clerk's <SignIn /> component. Style with full dark theme ($color-bg-base background, $color-primary accents).
1.8.3 Add user avatar to toolbar/activity bar using Clerk's <UserButton /> component.

✅ Phase 1 Complete Checklist

Vite + React client runs on localhost:5173
Express server runs on localhost:3001
MongoDB Atlas connection established
Clerk auth works — users can sign in/out
SCSS design system fully defined with all tokens
Monaco Editor renders with Cortex dark theme
3-panel App Shell layout renders correctly
File tree renders project files
Editor tabs open/close/switch correctly

[x] PHASE 2 — Decision Memory

PRD Reference: Section 6.3 (Decision Memory Feature), Section 9 Phase 2 (Week 3–4) Goal: Build the complete Decision Memory feature — MongoDB model, all CRUD APIs, Monaco gutter decorations, annotation drawer UI, Memory Vault page, and AI summarization.

⚠️ Re-read PRD Section 6.3 fully before starting this phase.

2.1 — Decision Memory Data Layer

2.1.1 Create server/models/DecisionMemory.js — Mongoose schema with ALL fields from PRD Section 6.3.
2.1.2 Add MongoDB indexes to DecisionMemory as per PRD Section 8.2.
2.1.3 Create server/routes/memory.routes.js — define all 6 endpoints from PRD Section 6.3.
2.1.4 Create server/controllers/MemoryController.js — implement full business logic for all 6 endpoints.

2.2 — AI Memory Summarization

2.2.1 Create server/services/GeminiService.js — initialize @google/generative-ai with GEMINI_API_KEY.
2.2.2 Wire GeminiService.summarizeMemories() into MemoryController.summarize().

2.3 — Memory API Client Layer

2.3.1 Create client/src/api/index.js — configure Axios instance with auth interceptor.
2.3.2 Create client/src/api/memoryApi.js — functions for CRUD and summarization.
2.3.3 Create client/src/hooks/useSocket.js — Socket.IO client hook.

2.4 — Monaco Gutter Decorations

2.4.1 In MonacoWrapper.jsx, call editor.deltaDecorations() to render amber gutter marks.
2.4.2 Implement hover tooltip on gutter marks.
2.4.3 Clicking a gutter mark opens the memory in the right feature panel.
2.4.4 Handle multiple memories on same file range.
2.4.5 Right-click context menu in Monaco editor — add "Add Decision Memory" option.

2.5 — Memory Annotation Drawer UI

2.5.1 Create client/src/features/memory/MemoryAnnotation.jsx.
2.5.2 Style the drawer using SCSS tokens.
2.5.3 Create client/src/hooks/useMemory.js.
2.5.4 Implement the "Add Memory" Feature CTA button in EditorToolbar.jsx.

2.6 — Memory Vault Page

2.6.1 Create client/src/pages/MemoryVault.jsx.
2.6.2 Create client/src/features/memory/MemorySearch.jsx.
2.6.3 Create client/src/features/memory/DecisionMemory.jsx card component.
2.6.4 Implement Timeline View tab in MemoryVault — renders memories sorted by createdAt in a vertical timeline. Each entry shows date, reason, category badge, and the codeSnapshot in a read-only Monaco diff viewer.
2.6.5 Implement "Summarize Decisions" button in MemoryVault.
2.6.6 Memory Vault accessible from Activity Bar icon and shortcut.

✅ Phase 2 Complete Checklist

PHASE 3 — Intent Mode

PRD Reference: Section 6.1 (Intent Mode Feature Spec), Section 9 Phase 3 (Week 5–6) Goal: Build the Intent Mode AI feature — GeminiService streaming, Intent panel UI, diff viewer, rate limiting, Groq fallback, and auto-memory creation.

⚠️ Re-read PRD Section 6.1 fully before starting this phase.

3.1 — GeminiService Streaming

3.1.1 Extend server/services/GeminiService.js — add streamAnalysis() method.
3.1.2 Create server/services/GroqService.js — fallback provider implementation.
3.1.3 Create server/utils/tokenEstimator.js.
3.1.4 Create server/utils/promptBuilder.js.

3.2 — Socket.IO Stream Relay

3.2.1 Create server/sockets/streamHandler.js.
3.2.2 Create server/sockets/intentStream.js to pipe tokens.
3.2.3 Wire Socket.IO handlers into server/index.js.

3.3 — Rate Limiting & Groq Fallback

3.3.1 Create server/middleware/RateLimit.js.
3.3.2 Implement provider fallback logic in IntentController.
3.3.3 Implement Token estimation check before AI call.

3.4 — Intent Mode API

3.4.1 Create server/routes/intent.routes.js.
3.4.2 Create server/controllers/IntentController.js.
3.4.3 Create server/models/IntentRun.js model.

3.5 — Intent Mode API Client & Hook

3.5.1 Create client/src/api/intentApi.js.
3.5.2 Create client/src/hooks/useIntentMode.js.

3.6 — Intent Mode UI

3.6.1 Create client/src/features/intent/IntentSelector.jsx.
3.6.2 Create client/src/features/intent/IntentResultPanel.jsx with diff viewer.
3.6.3 Create client/src/features/intent/IntentMode.jsx parent component.
3.6.4 Wire Intent Mode to "Intent Mode" CTA in toolbar.
3.6.5 Implement keyboard shortcuts for Intent Mode.
3.6.6 Implement "Accept" auto-memory creation.

✅ Phase 3 Complete Checklist

[x] PHASE 4 — Codebase Explainer

PRD Reference: Section 6.2 (Codebase Explainer), Section 9 Phase 4 (Week 7–8) Goal: Build the CodeParserService (AST-based), GraphBuilderService, D3 force-directed graph UI, 4 visualization layers, data flow tracer, dependency audit, and SVG/PDF export.

⚠️ Re-read PRD Section 6.2 fully before starting this phase.

4.1 — Code Parser Service

4.1.1 Install backend dependencies: acorn, estree-walker, archiver, @babel/parser.
4.1.2 Create server/utils/fileExtractor.js.
4.1.3 Create server/services/CodeParserService.js (AST-based).
4.1.4 Create server/services/GraphBuilderService.js.
4.1.5 Create client-side graph utils.

4.2 — AI File Summarization

4.2.1 Extend GeminiService.js with summarizeFile().
4.2.2 Implement batch-call for file summarization.

4.3 — Codebase Explainer API

4.3.1 Create server/models/CodebaseSnapshot.js.
4.3.2 Create server/routes/explainer.routes.js.
4.3.3 Create server/controllers/ExplainerController.js.
4.3.4 Create client/src/api/explainerApi.js.

4.4 — D3 Force-Directed Graph

4.4.1 Install D3.js in client.
4.4.2 Create client/src/features/explainer/DependencyGraph.jsx.
4.4.3 Create client/src/features/explainer/ExplainerNodePanel.jsx.

4.5 — 4 Visualization Layers

4.5.1 Create tab bar for 4 views.
4.5.2 File Dependencies tab: Renders graph.
4.5.3 Data Flow tab: Create FlowOverlay.jsx.
4.5.4 Dependency Audit tab: Treemap + list.
4.5.5 Component Tree tab: Top-down diagram.

4.6 — Explainer Page & Export

4.6.1 Create client/src/pages/ExplainerView.jsx.
4.6.2 Create client/src/hooks/useExplainer.js.
4.6.3 Implement Export to SVG/PDF.
4.6.4 Wire "Explain Codebase" button and shortcut.

✅ Phase 4 Complete Checklist

PHASE 5 — Polish & Launch

PRD Reference: Section 9 Phase 5 (Week 9–10), Section 5.4 (Data Flow), Section 8.1 (Rate Limiting), Section 10 (Deployment) Goal: Responsive design, full keyboard shortcut system, comprehensive error handling, skeleton loaders, performance optimization, and production deployment.

⚠️ Re-read PRD Sections 8, 9 (Phase 5), and 10 fully before starting this phase.

5.1 — Keyboard Shortcut System

5.1.1 Implement client/src/hooks/useKeyboardShortcuts.js.
5.1.2 Implement ALL shortcuts from PRD Section 7.3.
5.1.3 Create CommandPalette.jsx searchable modal.

5.2 — Error Handling

5.2.1 Every AI call has try/catch and inline error states.
5.2.2 Add loading states with Skeleton component.
5.2.3 Backend ErrorHandler.js catching all formatted errors.
5.2.4 Global toast notifications: client/src/components/Toast/Toast.jsx.
5.2.5 Handle Monaco file loading errors.

5.3 — Responsive Design

5.3.1 Responsive layout testing (1280px, 1440px, 1920px).
5.3.2 Feature panel/sidebar auto-collapse at smaller breakpoints.
5.3.4 Dynamic Bottom Panel height adjustment.

5.4 — Performance Optimization

5.4.1 Monaco Editor lazy loading with Suspense.
5.4.2 D3 graph virtualization for large graphs.
5.4.3 Large file handling performance mode in Monaco.
5.4.4 Implement response caching for Codebase Explainer.
5.4.5 Implement request deduplication.

5.5 — UI Polish

5.5.1 Add micro-animations to buttons, cards, and graph.
5.5.2 Settings page (client/src/pages/Settings.jsx) functional.
5.5.3 Empty states for all views.
5.5.4 Hexagonal background for Auth page.

5.6 — Production Deployment

5.6.1 Production build configuration in Vite.
5.6.2 Backend production security and headers (Helmet).
5.6.3 Deploy frontend to Vercel.
5.6.4 Deploy backend to Railway.
5.6.5 MongoDB Atlas IP whitelisting.
5.6.6 Clerk production keys setup.
5.6.7 End-to-end smoke testing.

✅ Phase 5 Complete Checklist

SUMMARY PROGRESS TRACKER

Phase	Description	Status
Phase 1	Foundation & Project Setup	🔄 Files Created - Most Working
Phase 2	Decision Memory	🔄 Files Created - Partially Working
Phase 3	Intent Mode	🔄 Files Created - Needs Verification
Phase 4	Codebase Explainer	🔄 Files Created - Partially Working
Phase 5	Polish & Launch	🔄 Files Created - Not Implemented

Current State:

All backend files created (models, routes, controllers, services, middleware, utils, sockets)
All frontend files created (components, features, pages, stores, hooks, api, styles)
Redis removed, MongoDB TTL indexes configured for rate limiting
Socket.IO refactored to separate module
Database connection integrated
Phase 1: Most features working (Monaco, SCSS, basic app shell)
Phase 2: Partially working (basic memory CRUD, Monaco gutter decorations, but timeline view not fully implemented)
Phase 3: Files created, needs verification of streaming and UI
Phase 4: Partially working (D3 graph works, but Flow/Deps/Components tabs are placeholders, ExplainerNodePanel missing)
Phase 5: Not implemented (keyboard shortcuts, error handling, responsive design, performance, deployment all unchecked)

Not Working / Placeholders:

Phase 2.6.4: Timeline view missing Monaco diff viewer
Phase 4.4.3: ExplainerNodePanel file doesn't exist
Phase 4.5.3: Data Flow tab is placeholder
Phase 4.5.4: Dependency Audit tab is placeholder
Phase 4.5.5: Component Tree tab is placeholder
Phase 5: All polish and deployment tasks unchecked

— Cortex Phased Plan v1.0 | Based on Cortex_PRD_v1.0.md | Shivam Garade | 2026 —

FilesExpand file tree

PHASES.md

Latest commit

History