Senior Brainstorm

Senior Brainstorm v6

Scope

Architecture design for educational SaaS platforms: stack selection, feature brainstorm, decision review, AI/LLM integration, agent-native system design.

Non-goals

• Simple CRUD tasks without architectural questions
• Tasks outside educational SaaS
• Single-framework questions without product context

Decision Framework

Every decision passes through this filter:

1. Stage -- MVP, growth, scale, enterprise
2. Team -- 1-3, 4-10, 10+
3. Budget -- bootstrap, funded, enterprise
4. Time-to-market -- week, month, quarter
5. Compliance -- none, GDPR, SOC 2, PCI DSS, FERPA, COPPA

Compliance Quick Reference

FERPA notes: Rights transfer to the student at age 18 OR upon enrollment in postsecondary education (whichever comes first), not solely based on age. Multiple non-consent disclosure exceptions exist: directory information, legitimate educational interest, health/safety emergencies, judicial order, and others (see 34 CFR Part 99).

COPPA notes: In educational contexts, schools may consent on behalf of students under 13, but the operator (your platform) still carries compliance responsibility for data handling, retention limits, and parental access rights.

When FERPA/COPPA applies: implement age-gating, parental consent flows, and audit logging for all data access. Separate data stores for minors is an optional isolation pattern (not a legal requirement) that simplifies compliance auditing and data retention enforcement.

Default Principles

• Start simple -- modular monolith, not microservices
• Optimize for reversibility -- easy to roll back decisions
• Avoid premature distribution -- do not split until it hurts
• Measure before scaling -- data, not intuition

Agent Native Architecture (Core Principle)

Every system must be agent-first: if an agent cannot operate it programmatically, the architecture is wrong.

This is not an afterthought -- it is a foundational design constraint equal in weight to security and scalability.

Principles

1. Backend is for agents. Frontend is for humans. Agents interact through APIs, tools, MCP -- never through UI. No feature should exist only behind a browser.
2. API-first design. Every capability exposed as a versioned, documented API endpoint before any UI is built. OpenAPI spec is the contract.
3. MCP server integration (recommended). As the system matures, expose MCP servers for agent discovery and tool use. At MVP stage, a well-designed REST API is sufficient; MCP can be added incrementally as the agent ecosystem grows.
4. CLI tooling. Every admin/ops action available as a CLI command. If you need a dashboard to do it, the architecture is incomplete.
5. Webhook-driven workflows. Events flow through webhooks/event bus, not polling. Agents subscribe to events and react autonomously.
6. Programmatic admin interfaces. User management, content moderation, analytics -- all accessible via authenticated API. Admin panels are convenience layers, not gates.

Patterns

Checklist (Gate: before approving any architecture)

• Can an agent create a user without a browser?
• Can an agent publish/unpublish content via API?
• Can an agent query analytics programmatically?
• Can an agent trigger payments/refunds via API?
• Are all admin actions available without UI?
• Does the system expose MCP server(s)? (recommended, not required at MVP)
• Are events published to a webhook/event bus?

Default Stack for New Projects (Opinionated)

For greenfield projects without legacy stack, start with opinionated defaults rather than open-ended stack selection. This reduces decision fatigue and produces consistent, maintainable systems.

Three default tracks — choose by team strength, SEO/SSR requirement, and AI/data-heaviness:

Track A: Lean Default (non-SSR projects)

Use for internal dashboards, admin panels, SPAs, mobile apps, desktop apps, bot control panels, APIs.

• Backend: TypeScript + Hono + Bun
• Frontend (SPA): Client React + Vite 8 (no SSR, no Next.js)
• Frontend (static): Vite 8 SSG
• Mobile: Expo + React Native
• Desktop: Electron (TS + React)
• DB: Managed Postgres (DO / fly.io / Supabase / Neon) + Prisma
• Storage: Tigris or native cloud

Full details: references/stacks-lean-default.md.

Track B: EdTech SaaS (SSR/SEO required)

Use for course platforms, marketing sites, content-heavy public pages.

• Frontend: Next.js 16 (App Router) — see references/stacks-frontend.md
• Backend: Node.js 22 + Fastify 5 — see references/stacks-backend.md
• DB: Postgres (managed) + Redis for cache/queues
• Auth: Clerk / Auth0 / NextAuth depending on enterprise needs

Track C: Python + Supabase (AI/bots/data)

Use for Telegram bots with admin, AI/RAG projects, data-heavy backends, teams stronger in Python.

• Backend: Python 3.12 + FastAPI 0.115+ — see references/stacks-python-supabase.md
• Bot framework: aiogram 3.x or python-telegram-bot v21+
• BaaS: Supabase (Postgres + Auth + Storage + Realtime + Edge Functions)
• Frontend: Next.js 16 (App Router) или Vite + React
• ORM: SQLAlchemy 2.x async (или SQLModel) с asyncpg

For data layer choice across all tracks (Supabase vs Yandex Cloud vs self-hosted), see references/stacks-data-layer.md.

Choosing Between Tracks

Scale defaults for all tracks: target 10K users initially. No microservices, no Kubernetes before 10K. Managed DB, managed storage, single service.

AI/LLM Integration Architecture

RAG pipelines, AI tutoring patterns, prompt observability, guardrails, vector DB selection. -> See references/ai-llm.md for detailed options, tables, and selection guidance.

Real-Time Collaboration Patterns

WebSocket, CRDT, WebRTC, SSE, Liveblocks -- when to add real-time and how to scale it. -> See references/realtime.md for technology options, architecture patterns, and scaling.

LTI (Learning Tools Interoperability)

LMS integration via LTI 1.3/Advantage, OneRoster/SIS sync, SCORM/xAPI/cmi5 standards. -> See references/lti.md for versions, implementation checklist, and content packaging.

Build vs Buy Decision Matrix

Component sourcing decisions for EdTech: scoring matrix, decision rules, common SaaS options. -> See references/build-vs-buy.md for the full matrix and buy options table.

Golden Question Bank (Discovery Phase)

Structured questions for the Discovery phase. Select relevant categories based on project scope.

Business

1. What is the primary revenue model? (subscription, one-time, cohort-based, B2B licensing)
2. Target user count at launch? In 12 months?
3. Who are the end users? (self-learners, K-12 students, corporate employees, university)
4. What is the competitive differentiator vs Teachable/Udemy/Coursera?
5. Is B2B (selling to institutions) in scope? Timeline?
6. What is the content creation workflow? (solo instructor, team, UGC)
7. Budget for infrastructure? Monthly ceiling?
8. Existing audience/distribution channel?

Technical

1. Existing codebase/tech stack? Migration constraints?
2. Team size and expertise? (frontend, backend, DevOps, ML)
3. Expected content types? (video, text, interactive, code exercises, quizzes)
4. Integration requirements? (LMS via LTI, CRM, payment providers, analytics)
5. Mobile app needed? Timeline? (responsive web, PWA, native)
6. Expected concurrent users during peak? (live events, launches)
7. Data residency requirements? (EU, US, specific country)
8. Existing infrastructure? (cloud provider, CI/CD, monitoring)

Pedagogy

1. What learning model? (self-paced, cohort, live, blended)
2. Assessment types? (quizzes, projects, peer review, AI-graded)
3. Certification/credentialing needed? (certificates, badges, transcripts)
4. Progress tracking granularity? (course, module, lesson, activity)
5. Adaptive learning or fixed curriculum?
6. Instructor-student interaction model? (forum, chat, 1:1, office hours)
7. Content versioning? (update in place, or preserve student's enrolled version)
8. Accessibility requirements? (WCAG level, screen reader, captions)

Compliance

1. User age range? (adults only, 13+, under 13 -- triggers COPPA)
2. Geographic scope? (US -- FERPA, EU -- GDPR, both)
3. Handling student education records from institutions? (FERPA)
4. Payment card data handling? (PCI DSS scope)
5. Data retention policy requirements?
6. Right to deletion / data portability needed?
7. Audit trail requirements? (who accessed what, when)
8. Third-party data processor agreements needed?

Deliverables

• Discovery questions (context + constraints) -- use Golden Question Bank
• Options matrix (2-3 approaches with tradeoffs)
• ADR (Architecture Decision Record) -- template: templates/adr-template.md
• Phased implementation plan
• Risk register

EdTech Domain

Video delivery, entitlements, instructor workflows, cohort/live learning, progress tracking, certificates, content moderation, analytics (completion rates, engagement), AI tutoring, LTI integration, real-time collaboration, agent-operated admin workflows.

Knowledge Base

Detailed reference for each domain. Load only the relevant file:

Templates

Adaptive Workflow

Small task (< 1 day)

1. Context -> 2. Decision -> 3. ADR -> done

Greenfield project

1. Discovery -- constraints, success criteria, budget, timeline. Use Golden Question Bank (select relevant categories).
2. Domain modeling -- bounded contexts, entities, events. Read references/architecture.md
3. Architecture options -- 2-4 approaches with tradeoffs, cost/complexity scoring. Apply Agent Native checklist. Run Build vs Buy matrix for each component.
4. Design document -- stack, DB schema, API, infra. Read relevant references/stacks-*.md
5. Gate -- user approves or corrects
6. Implementation plan -- phases, tickets, dependencies

Re-architecture / Migration

1. Audit current state (bottlenecks, tech debt, risks)
2. Target architecture (apply Agent Native principles)
3. Migration plan (strangler fig, parallel run, data migration)
4. Risk register
5. Gate: approval

Incident / Audit

1. Investigation (logs, traces, root cause)
2. Immediate fix
3. Post-mortem + systemic fix
4. Prevention (monitoring, tests, runbook)

Cost/Complexity Scoring

Before recommending advanced architecture:

Score < 6: modular monolith. Score 6-10: extract on pressure. Score > 10: service-oriented.

Artifacts per Stage

• Discovery: structured questions (from Golden Question Bank), constraints list
• Options: tradeoff matrix, cost/complexity scores, Build vs Buy matrix (use templates/options-matrix.md)
• Decision: ADR (use templates/adr-template.md)
• Plan: phased roadmap with milestones
• Risk: assumptions log, decision log, open questions

Source Discipline

Authoritative sources (official docs, RFC, OWASP) for recommendations. Blog posts for supporting context. Community posts (DEV.to, reels) only for discovery, never as basis for recommendations.