Version: 3.0.0 APPROVED | Last Updated: 2025-11-11
This repository contains the complete specifications for MyCastle, an ESL school operations platform built on the 8-MCP domain-driven architecture with extensibility for future domain MCPs. It covers timetable management, CEFR-driven lesson planning, attendance tracking, student profiles, and AI-assisted workflows through role-specific MCP servers.
Readiness hierarchy (SSOT):
- MVP_SPEC_REVIEW.md = Authority (readiness)
- STATUS.md = Signal (derived)
- ROADMAP.md = Intent (future)
- project-review.md = Learning (post-hoc)
MVP policy decisions:
- /api/admin/ routes are admin-only*
- Admin attendance does NOT require hash-chain compliance for MVP
These three documents form the authoritative spine of the project and are updated with every commit:
What the system must do and why.
- Goals (MoSCoW), stakeholders, user stories
- Functional and non-functional requirements
- Data requirements, compliance, acceptance criteria
- Success metrics and traceability
How the system fulfils the requirements.
- Architecture (MCP, Next.js, Supabase)
- Domain model, data flows, APIs
- Security (RLS, JWT, encryption)
- Performance strategies, observability
How work is executed to implement the design.
- Work breakdown structure (WBS) by Epic
- Actionable tasks with acceptance criteria
- Testing strategy, CI/CD pipeline
- Traceability (REQ → DESIGN → TASK)
These documents are living and must be kept aligned with implementation.
Updated: 2026-01-02 - Consolidated from 27 → 12 core documents
MyCastle/
├── README.md # This file - Navigation hub
│
├── Core Specification ("The Spine")
├── REQ.md # ✅ Requirements Specification (v3.0.0)
├── DESIGN.md # ✅ Design Specification (v3.0.0)
├── TASKS.md # ✅ Task Specification (v3.0.0)
│
├── Living Documents (Updated Weekly)
├── STATUS.md # ⭐ Current sprint tasks with 20-min subtasks
├── ROADMAP.md # Phases 1-4 (105 tasks)
│
├── Operational Guides
├── GETTING-STARTED.md # Quick start + detailed setup + overview
├── TESTING.md # All testing procedures (unit, E2E, RLS)
├── DEPLOYMENT.md # Production deployment guide
│
├── Reference Documents
├── docs/
│ ├── reference/
│ │ ├── 8-MCP-IMPLEMENTATION-PLAN.md
│ │ ├── BUSINESS_VALUE_PRIORITIES.md
│ │ └── FLEXIBLE_ENROLLMENTS.md
│ │
│ ├── archive/ # Historical documents
│ │ ├── sprints/ # Sprint retrospectives
│ │ ├── analyses/ # Gap analyses and reviews
│ │ ├── PROGRESS.md # Old progress tracking
│ │ └── NEXT_STEPS_GUIDE.md # Old setup guide
│ │
│ └── migration/
│ └── MIGRATION_GUIDE.md
│
├── Technical Specifications
├── spec/ # Detailed MCP architecture specs
│ ├── 01-overview.md # Project objectives, stakeholders
│ ├── 02-system-architecture.md # System architecture details
│ ├── 03-mcp.md # MCP protocol implementation
│ ├── 04-admin-mcp.md # Admin MCP specification
│ ├── 05-teacher-mcp.md # Teacher MCP specification
│ ├── 06-student-mcp.md # Student MCP specification
│ ├── 07-agents.md # Host orchestration patterns
│ ├── 08-database.md # Complete database schema
│ ├── 09-mcp-interaction-patterns.md
│ └── table-of-contents.md
│
└── Implementation
└── app/ # Next.js application code
- GETTING-STARTED.md - Project overview and current status
- STATUS.md - Current sprint progress (updated weekly)
- REQ.md - Complete requirements specification
- GETTING-STARTED.md - 5-minute quick start or detailed setup
- STATUS.md - See current sprint tasks with 20-min subtasks
- TESTING.md - Run tests and verify setup
- DESIGN.md - Technical architecture and patterns
- TASKS.md - Work breakdown structure (42 tasks)
- spec/ - Detailed MCP architecture specifications
- Check STATUS.md for current sprint tasks
- Each task has 20-minute subtasks for easy tracking
- Link to requirements in REQ.md
- Review design in DESIGN.md
- Implement with traceability comments
- Run
npm run checkbefore committing - Update STATUS.md with progress
Core MCPs (all ≤10 tools):
- ✅ Identity & Access MCP (6 tools) - User auth, roles, permissions
- ✅ Academic Operations MCP (10 tools) - Programmes, courses, scheduling
- ✅ Attendance & Compliance MCP (8 tools) - Registers, visa tracking
- ✅ Finance MCP (9 tools) - Invoicing, payments, reconciliation
- ✅ Student Services MCP (9 tools) - Accommodation, letters, certificates
- ✅ Operations & Quality MCP (8 tools) - Backups, QA, CPD
- ✅ Teacher MCP (10 tools) - Lesson planning, grading, attendance
- ✅ Student MCP (10 tools) - Timetable, AI tutor, progress tracking
Future Extensibility:
- ⏭️ Parent MCP - Parent portal (≤10 tools)
- ⏭️ Partner MCP - School partnerships (≤10 tools)
- ⏭️ Analytics MCP - BI and reporting (≤10 tools)
- ⏭️ Marketing MCP - CRM and campaigns (≤10 tools)
- ⏭️ Custom domain MCPs - Easy to add without modifying existing MCPs
Migration Strategy: 4-phase rollout (see TASKS.md §4.3.1)
| Technology | Version | Purpose |
|---|---|---|
| TypeScript | ^5 | Type-safe development across entire stack |
| Next.js | 16.0.1 | Full-stack React framework with API routes |
| Node.js | ^20 | Server runtime for MCP orchestration |
| Technology | Version | Purpose |
|---|---|---|
| React | 19.2.0 | UI component library |
| React DOM | 19.2.0 | React rendering for web |
| Tailwind CSS | ^4 | Utility-first CSS framework |
| Technology | Version | Purpose |
|---|---|---|
| Next.js API Routes | 16.0.1 | RESTful endpoints and MCP orchestration |
| MCP SDK | ^1.21.1 | Model Context Protocol implementation |
| Zod | ^4.1.12 | Runtime schema validation |
| Technology | Version | Purpose |
|---|---|---|
| Supabase | ^2.80.0 | Primary database platform with RLS |
| PostgreSQL | - | Underlying relational database |
| Drizzle ORM | ^0.44.7 | Type-safe SQL query builder |
| Drizzle Kit | ^0.31.6 | Schema migrations and management |
| postgres | ^3.4.7 | PostgreSQL client for Node.js |
| Technology | Version | Purpose |
|---|---|---|
| Supabase Auth | ^2.80.0 | JWT-based authentication |
| Supabase SSR | ^0.7.0 | Server-side rendering auth support |
| Technology | Version | Purpose |
|---|---|---|
| OpenAI API | ^6.8.1 | LLM integration (model-agnostic design) |
| Technology | Version | Purpose |
|---|---|---|
| Jest | ^30.2.0 | Unit and integration testing |
| Testing Library | ^16.3.0 | React component testing |
| jest-dom | ^6.9.1 | Custom Jest matchers for DOM |
| Technology | Version | Purpose |
|---|---|---|
| ESLint | ^9 | Code linting and quality checks |
| Prettier | ^3.6.2 | Code formatting |
| tsx | ^4.20.6 | TypeScript execution for scripts |
| Archon | - | MCP inspector for development |
| Layer | Technology | Notes |
|---|---|---|
| MCP Protocol | JSON-RPC 2.0 over stdio/HTTPS | stdio (dev), HTTPS (prod) |
| Multi-tenancy | Row-Level Security (RLS) | Database-enforced tenant isolation |
- Domain-Driven Design: 8 focused MCPs (all ≤10 tools) vs bloated 3-MCP design
- Host-Mediated Communication: All MCP servers communicate through the Host (no direct MCP-to-MCP)
- Scope-Based Routing: Fine-grained authorization (identity:, finance:, academic:*, etc.)
- Tenant Isolation: Multi-tenancy ready with
tenant_idand RLS policies - Extensibility by Design: Add new domain MCPs without modifying existing ones
- Spec-First Development: All changes documented before implementation
- Security by Design: JWT verification, RLS, audit logging throughout
- Performance: Distributed load, domain-specific caching, simpler RLS per MCP
- Table of Contents - Complete navigation
- System Architecture - Detailed architecture diagrams and component descriptions
- Admin MCP - Complete specification for MVP MCP server (resources, tools, prompts)
- Database Schema - Full Drizzle schema with ERD, RLS policies, and views
- Agent Orchestration - Host patterns for multi-MCP coordination
- GDPR-Aligned: Data minimization, purpose limitation, access control
- RLS (Row-Level Security): Enforced at database level for tenant isolation
- JWT Authentication: Supabase Auth with JWKS verification
- Audit Logging: All significant actions logged immutably
- Context Isolation: MCP servers cannot access each other's data directly
- Manage users (add, modify, delete)
- Create and manage classes
- Track attendance and bookings
- Generate Excel/CSV exports from templates
- View payment summaries and create invoices
- System backups and audit logs
- Generate lesson plans and quizzes
- Auto-grade assignments
- Analyze student performance
- Record attendance and grades
- Send class announcements
- Get personalized tutoring and homework help
- Take practice quizzes
- Track learning progress
- Access course materials
- Receive study guidance
This project follows a spec-first approach:
- Specification → Design documented before implementation
- Schema Definition → Database tables defined with Drizzle
- MCP Server → Tools, resources, prompts implemented
- Host Integration → Connect MCP to Host service
- Testing → Archon inspection + unit/integration tests
- Deployment → Local dev (stdio), Production (HTTPS)
| Section | Status | Description |
|---|---|---|
| 1-8 | ✅ Complete | Overview, Architecture, MCP, Admin/Teacher/Student MCPs, Agents, Database |
| 9 | ⏳ To Detail | Testing strategies |
| 10 | ⏳ To Integrate | User stories from original spec |
| 11 | ⏳ To Detail | Deployment procedures |
| 12 | ⏳ To Create | Appendices, glossary, API reference |
This is a living specification. Changes should follow this process:
- Discuss proposed changes
- Update relevant spec documents
- Update table of contents if structure changes
- Increment version in document status
- Commit with clear description
Every task in TASKS.md links to:
- User Stories in REQ.md (§5) via REQ-T-, REQ-A-, REQ-S-* IDs
- Design Sections in DESIGN.md via § references
- Acceptance Criteria (GIVEN-WHEN-THEN format)
Example Traceability Chain:
User Story (REQ-T-001): Generate CEFR-aligned lesson plan
↓
Design (DESIGN §6): Lesson Planning Flow (AI-Assisted)
↓
Tasks: T-031 (API), T-032 (Schema), T-033 (Cache)
↓
Implementation: Code with comments linking back to REQ-T-001
↓
Tests: E2E test named "REQ-T-001: Generate lesson plan"
This ensures bidirectional traceability: from requirements to implementation, and from code back to requirements.
Status: ✅ Architectural decision finalized and approved for implementation
Core Changes:
- ✅ Split Admin MCP into 6 domain MCPs (Identity, Academic, Attendance, Finance, Student Services, Ops)
- ✅ Optimized Teacher MCP (12 → 10 tools)
- ✅ Optimized Student MCP (14 → 10 tools)
- ✅ All 8 MCPs now ≤10 tools (compliance with architectural constraint)
- ✅ Added 34 migration tasks (T-110 to T-143) with 4-phase rollout plan
- ✅ Updated C4 architecture diagrams with scope-based routing
- ✅ Fine-grained authorization scopes (identity:, finance:, academic:*, etc.)
- ✅ Total: 76 tasks (42 core + 34 migration)
Extensibility:
- ✅ Clear pattern for adding future domain MCPs (Parent, Partner, Analytics, Marketing)
- ✅ Standard MCP interface with maxTools=10 constraint
- ✅ Independent deployment model (no cascading changes)
- ✅ Extension guidelines and technical requirements documented
- ✅ Example implementations provided (Parent MCP with 10 tools)
Benefits:
- ✅ Better security: least privilege, smaller attack surface per MCP
- ✅ Better performance: distributed load, domain-specific caching
- ✅ Easier maintenance: clear domain boundaries, focused responsibility
- ✅ Future-proof: seamless addition of new domains without refactoring existing MCPs
- ✅ Added REQ.md, DESIGN.md, TASKS.md as project spine
- ✅ Reconciled MCP architecture with traditional requirements
- ✅ Established traceability between all specs
- ✅ User stories mapped to detailed tasks
- ✅ 42 tasks defined across 11 epics
- ✅ 4 milestones with clear exit criteria
- Complete MCP architecture specs (Admin, Teacher, Student MCPs)
- Interaction patterns and orchestration details
- Shared services architecture
- Merged original spec.md and esl-mcp-spec content
- Completed sections 1-8
- Established MVP priorities (Admin MCP + Host)
Eoin Malone (with Claude Code)
[To be specified]
Specification Status: ✅ v3.0.0 APPROVED - Complete and Aligned (REQ ↔ DESIGN ↔ TASKS) Architectural Decision: ✅ 8-MCP domain-driven architecture with extensibility approved 2025-11-11 Last Updated: 2025-11-11 Version: 3.0.0