Single execution track

Sensei implementation roadmap

The repo now uses one migration plan with v4 as the target architecture and the current SPA treated as the starting point, not the finish line.

Current

Cloudflare Pages-hosted Vite app + React Router + Worker API + Neon + Drizzle + database-backed session auth

Target

Cloudflare Pages + Worker API + Neon + Drizzle + Lucia-style session auth

Use v4 as the platform reference while keeping the current Vite shell production-ready and dependency-ordered.

Phases

7

Tasks

18

Completed

16

In Progress

0

Guiding principles

Keep the app working after every phase.

Replace duplicate contracts before adding backend complexity.

Move mock features to real persistence feature-by-feature.

Ship resilience as code, not as team discipline.

Next move

Finish phase 1 cleanly

The current pass is about reducing duplication, keeping progress visible, and preparing the repo for the platform shell migration.

Open platform map
Completed

Phase 1. Foundation Alignment

Turn the architecture drafts into one executable plan and reduce duplication inside the current frontend.

Done when

The repo has one canonical roadmap, the app can display it, and AppContext stops maintaining separate copies of shared seed data.

Create one canonical roadmap

Completed

Consolidate v1-v4 into a single execution document that reflects the current repo reality.

sensei-implementation-roadmap.md

Surface the roadmap inside the app

Completed

Add a route and typed roadmap data so progress can be tracked from inside the product shell.

src/app/data/implementation-roadmap.tssrc/app/pages/RoadmapPage.tsxsrc/app/pages/PlatformPage.tsx

Reuse shared seed/domain data in AppContext

Completed

Stop duplicating notification, application, and community seed data inside the active context layer.

src/app/context/AppContext.tsxsrc/app/data/appSeed.ts

Normalize page consumption of richer state models

Completed

Update feature pages to use the shared application, notification, and community shapes consistently.

src/app/pages/ApplicationsPage.tsxsrc/app/pages/NotificationsPage.tsxsrc/app/pages/CommunityPage.tsx
Completed

Phase 2. Platform Shell Migration

Prepare the repository for the Cloudflare platform structure without losing the current UI.

Done when

Package boundaries for app, api, and shared contracts exist and the web shell remains stable.

Introduce package boundaries

Completed

Split responsibilities into app, api, shared schema, and config layers.

apps/packages/src/app/platform-manifest.tsx

Keep the route shell production-ready

Completed

Preserve the current UI while mapping route ownership to the future platform boundary.

src/app/routes.tssrc/app/platform-manifest.tsxsrc/app/pages/PlatformPage.tsx
Completed

Phase 3. Backend Foundation

Stand up the API, database, auth, validation, logging, and rate limiting expected by v4.

Done when

Auth and migrations run end-to-end and protected API routes are stable.

Create the Worker API layer

Completed

Add Hono-style route handling, middleware order, and error wrapping.

apps/api/src/index.tsapps/api/src/routesapps/api/src/middleware

Connect Neon and Drizzle

Completed

Introduce reproducible migrations and the real persistence layer.

apps/api/src/dbapps/api/drizzle.config.tsapps/api/drizzle

Implement auth flows

Completed

Signup, login, verification, reset, and session revocation now run through database-backed Worker APIs.

apps/api/src/lib/auth.tsapps/api/src/routes/auth.tsapps/api/src/repositories/auth.ts
Completed

Phase 4. Real Data Layer

Replace the frontend mock layer feature-by-feature with DB-backed APIs and search.

Done when

Core data pages are API-backed and critical user flows no longer depend on hardcoded primary storage.

Move universities, courses, and scholarships to real APIs

Completed

Catalog data is seeded into the backend and served through API routes that power the feature pages.

apps/api/src/data/bootstrap.tsapps/api/src/repositories/catalog.tssrc/app/lib/api.ts

Persist dashboard and content flows

Completed

Applications, notifications, community, content, FAQ, and quiz results now sync through API-aware flows instead of in-memory handlers.

src/app/context/AppContext.tsxsrc/app/lib/api.tsapps/api/src/routes/applications.tsapps/api/src/repositories/applications.tsapps/api/src/routes/notifications.tsapps/api/src/repositories/notifications.tsapps/api/src/routes/community.tsapps/api/src/repositories/community.tsapps/api/src/routes/content.tsapps/api/src/repositories/content.tsapps/api/src/routes/quiz.tsapps/api/src/repositories/quiz.tsapps/api/src/routes/faq.tsapps/api/src/repositories/faq.ts
Completed

Phase 5. SEO, Performance, and Resilience

Add the operational pieces that v2-v4 spelled out: SEO, caching, retry safety, and circuit protection.

Done when

Performance gates are enforced and resilience behavior is structural.

Implement metadata and discovery files

Completed

Meta, canonical URLs, JSON-LD, sitemap, robots, and route-level metadata are now wired into the app shell.

public/robots.txtpublic/sitemap.xmlsrc/app/components/RouteMetadata.tsxsrc/app/seo/routeMetadata.tsvite.config.ts

Add outbox, rate-limit, timeout, and circuit protections

Completed

Telemetry intake, sliding-window rate limiting, outbox visibility, timeout wrappers, and circuit protection are structural in the API layer.

apps/api/src/lib/timeout.tsapps/api/src/lib/resilience.tsapps/api/src/lib/rate-limit.tsapps/api/src/repositories/outbox-events.tsapps/api/src/routes/telemetry.tssrc/app/lib/web-vitals.ts

Enforce bundle budgets in CI

Completed

The web app now ships with a build-time bundle budget check that can fail CI when major assets grow past agreed limits.

package.jsonscripts/check-bundle-budget.mjsvite.config.ts
Completed

Phase 6. Feature Completion

Finish the end-to-end student and admin features on real workflows.

Done when

Community, resources, CMS, recommendations, admin moderation, FAQ, and audit workflows are functional end-to-end.

Deliver real community and moderation workflows

Completed

Posts, replies, reports, moderation queues, and admin resolution flows now run through shared API boundaries.

src/app/pages/CommunityPage.tsxsrc/app/context/AppContext.tsxapps/api/src/routes/community.tsapps/api/src/repositories/community.ts

Wire the admin panel to real APIs

Completed

Replace static admin panels with authenticated moderation, CMS, resource, FAQ, telemetry, and audit workflows.

src/app/pages/AdminPage.tsxsrc/app/pages/FaqPage.tsxapps/api/src/routes/admin.tsapps/api/src/routes/content.tsapps/api/src/routes/faq.ts
Deferred

Phase 7. AI and Global Expansion

Add AI assistants and internationalization only after the core platform has real usage data.

Done when

The product is stable, measured, and ready to absorb the extra operational complexity.

Add MCP and agent workflows in sequence

Deferred

MCP tools first, then richer agentic behavior after operational maturity.

future api workspace

Add Urdu and RTL support

Deferred

Globalization follows proven traction in the core Pakistan market.

future app shell