# StudyFlow Master Implementation Roadmap This is the primary build-order document for StudyFlow. Use it as the top-level execution guide, and use the other planning files as supporting references for billing, auth, workflows, helper services, and pricing detail. ## What We Are Building StudyFlow is a SaaS document-understanding workspace with this product order: 1. Public landing page 2. Sign up / sign in 3. Protected app shell 4. Upload a document 5. Get a deterministic, user-friendly HTML workspace 6. Ask a strictly grounded AI chat assistant questions about that document 7. Optionally use premium AI study tools: - study-pack generation - infographic generation for eligible topics The MVP is not "an AI study tool that also accepts documents." It is "a document workspace product with grounded AI on top." ## Core Product Decisions Already Locked - Supported MVP uploads: `.txt`, `.pdf`, `.docx` - No-plan users can sign in and use one limited-size deterministic document-transform trial - No-plan users do not get AI features by default - Duplicate uploads are blocked by fingerprint and linked to the existing project - If a user wants to parse the same file again, they must delete the existing project first - Grounded chat must answer only from retrieved document evidence - Unsupported chat answers must be explicit, not guessed - Stripe is the source of truth for billing state - Local backend state is the source of truth for entitlements and usage - n8n executes already-authorized workflows; it does not decide plan access ## MVP vs Later ### MVP - Public marketing site - Auth - Billing shell - Project list - Upload - Deterministic workspace transform - Retrieval - Strict grounded chat - Duplicate blocking - Basic/Plus/Ultra plan enforcement ### Post-MVP - Premium OCR recovery - Study-pack generation - Infographic generation - More advanced retention/export features - Deeper document versioning surfaced in the UI Important boundary: - The architecture may keep room for `document_versions` - The MVP user-facing behavior should still be simple project-level duplicate blocking ## System Shape ### Product surfaces - Public: - `/` - `/pricing` - `/signup` - `/login` - Private: - `/app` - `/app/documents` - `/app/documents/:documentId` - `/app/settings` ### Core services - `studyflow-web-app` - `studyflow-auth` - `studyflow-db-api` - `studyflow-extractor` - `studyflow-template-renderer` - `studyflow-retrieval` - `studyflow-ai-service` - `n8n` For MVP implementation, some helper services can be combined if that reduces delivery risk. The cleanest acceptable MVP simplification is: - `studyflow-web-app` - `studyflow-auth` - `studyflow-db-api` - one combined `studyflow-processing-service` that owns extraction, rendering, retrieval, and grounded chat - `n8n` That simplification is acceptable as long as API boundaries remain clear. ## Milestones ## Milestone 0: Foundation and Shared Conventions Goal: - Set the rules that prevent rework later. Build: - environment and secret conventions - shared IDs and naming conventions - shared error shape - project/document fingerprinting rule - internal status enums Must define: - `draft`, `duplicate_blocked`, `processing`, `ready`, `failed`, `deleting` - processing stages: - `uploading` - `extracting` - `rendering` - `indexing` - `study_pack_generating` - `complete` Done means: - all services agree on IDs and status values - duplicate detection strategy is fixed - API error responses have one stable format ## Milestone 1: Public Product and Auth Shell Goal: - Make StudyFlow feel like a real product before any workflow logic. Build: - public landing page - pricing page - sign-up and sign-in - protected app shell - session handling - authenticated user context Done means: - unauthenticated users can discover the product and create accounts - authenticated users can enter `/app` - no-plan users see the shell and their limited trial state Acceptance criteria: - public routes render cleanly - auth session persists correctly - protected routes redirect correctly - the app shell can show plan and entitlement state ## Milestone 2: Billing and Entitlement Bridge Goal: - Make access decisions reliable before expensive actions exist. Build: - Stripe products and prices - Stripe Checkout entry - Stripe Customer Portal entry - webhook handling - local subscription state - entitlement read endpoints Done means: - app can distinguish: - no-plan - Basic - Plus - Ultra - plan state is available in the protected shell - gated UI can render honestly Acceptance criteria: - subscription changes update local entitlement state - no-plan users can access only the allowed trial behavior - paid users receive the correct unlocked features ## Milestone 3: Project Model, Upload Safety, and Duplicate Blocking Goal: - Accept only safe uploads and stop duplicate project drift. Build: - upload validation - MIME and extension checks - size checks - parser-safe rejection rules - duplicate fingerprint check - project creation rules Done means: - only `.txt`, `.pdf`, `.docx` are accepted - bad/corrupt/password-protected files are rejected clearly - duplicates do not enter the workflow - duplicate uploads link back to the existing project Acceptance criteria: - duplicate upload warning is surfaced before workflow dispatch - users can see their project list and reopen existing projects - reparsing the same file is blocked until deletion ## Milestone 4: Deterministic Document Workspace Goal: - Deliver the first real product value without AI dependency. Build: - extraction - extracted text persistence - deterministic HTML transformation - workspace persistence - project detail page Done means: - a user can upload one supported file - the system extracts text - the system renders a readable workspace - the project becomes `ready` Acceptance criteria: - no AI is required for the main workspace transform - no-plan trial works here - project page renders stable sections from extracted content ## Milestone 5: Project List and Processing-State UX Goal: - Make the app feel trustworthy while work is in flight. Build: - project list page - project detail page states - progress UI for upload/extract/render/index - failure UI - retry/delete/reopen actions Done means: - users always know what state a project is in - failed projects explain the failed stage - ready projects can be reopened at any time Acceptance criteria: - dashboard shows status, last updated time, and next action - processing states are consistent with backend status enums - duplicate-blocked and failed states are visually distinct ## Milestone 6: Retrieval and Grounded Chat Goal: - Add the first paid AI feature, but with strong trust rules. Build: - document chunking and indexing - retrieval endpoint - grounded chat endpoint - conversation persistence - citations in answers Done means: - chat answers are based on retrieved evidence only - unsupported questions return an honest refusal - answers carry source metadata Acceptance criteria: - chat is blocked for no-plan users by default - citations are present for supported answers - prompt injection inside uploaded text does not alter assistant behavior - low-quality extraction can trigger partial support or refusal ## Milestone 7: Usage Metering and Reservation Logic Goal: - Make billing defensible before premium actions expand. Build: - entitlement check endpoint - usage reservation flow - success-only consumption - reservation expiry - usage event logging Done means: - expensive actions do not burn twice on retry - failed actions do not consume usage - user-visible quota states are accurate Acceptance criteria: - grounded chat usage burns only on successful save - uploads/study-pack/infographic usage follow the same reservation pattern - usage counters are explainable from logged events ## Milestone 8: Premium Study Tools Goal: - Add the optional study layer without changing the product identity. Build: - standard study-pack generation - optional deeper study-pack mode - premium UI gating Done means: - Plus and Ultra can generate study tools - Basic stays focused on workspace + grounded chat Acceptance criteria: - study-pack generation is clearly a premium action - usage is metered by credit, not by vague “unlimited AI” - failure does not consume credits ## Milestone 9: Premium OCR and Infographics Goal: - Add high-cost premium value only after the core product is stable. Build: - premium OCR recovery path - infographic eligibility analysis - infographic generation - infographic credit metering Done means: - low-quality docs can be upgraded selectively - infographic generation appears only where it fits - Ultra gating behaves honestly Acceptance criteria: - only infographic-eligible topics show the action - Basic/Plus see a locked upgrade state, not a broken control - Ultra users with no credits see an exhausted state ## Milestone 10: n8n Activation and Operations Hardening Goal: - Move from planning artifacts to safe live orchestration. Build: - helper endpoints actually implemented - n8n workflow endpoint configuration - workflow activation - review queue wiring - retry rules - operational logs and alerts Done means: - imported StudyFlow workflows can run against real services - failures land in review/error handling paths - the app and workflows agree on status updates Acceptance criteria: - `StudyFlow Document Workspace Pipeline` can process a real upload - `StudyFlow Grounded Chat` can answer a real grounded question - `StudyFlow Workflow Errors` captures failed runs cleanly ## Recommended Service Build Order For the fastest stable path, build in this order: 1. `studyflow-web-app` 2. `studyflow-auth` 3. Stripe + entitlements bridge 4. `studyflow-db-api` 5. upload validation + duplicate blocking 6. `studyflow-extractor` 7. `studyflow-template-renderer` 8. project list and project detail shell 9. `studyflow-retrieval` 10. `studyflow-ai-service:/grounded-chat` 11. usage reservations and logging 12. premium study-pack generation 13. premium OCR and infographic generation 14. full n8n activation ## MVP Definition of Done StudyFlow MVP is done when: - users can sign up and sign in - no-plan users can perform one limited deterministic document transform - paid users can upload supported documents safely - duplicate uploads are blocked and linked to the existing project - users can reopen projects from a project list - each ready project has a deterministic document workspace - Basic users can use grounded chat with citations - unsupported grounded answers are explicit - billing and entitlements are enforced server-side - usage is consumed only on successful completion Study-pack generation and infographics are not required for MVP completion. ## Immediate Next Build Slice If we start implementation tomorrow, the first slice should be: 1. `studyflow-web-app` 2. `studyflow-auth` 3. protected app shell 4. pricing shell 5. entitlement-aware dashboard shell Why this first: - it makes the product real - it gives us the correct place to attach uploads, gating, and billing - it avoids building backend workflows before the user-facing app contract is clear ## Supporting Documents Use these only as supporting detail: - `PRODUCT_STRATEGY.md` - `HELPER_SERVICES_IMPLEMENTATION_PLAN.md` - `BILLING_AND_ENTITLEMENTS_PLAN.md` - `STRIPE_AUTH_ENTITLEMENTS_INTEGRATION_PLAN.md` - `AUTH_AND_APP_SHELL_IMPLEMENTATION_PLAN.md` - `studyflow-document-pipeline.runbook.md` If any of those conflict with this roadmap, update them to match this file rather than creating a second competing build order.