Skip to main content

Framework Development Checklists

This folder contains detailed phase-by-phase checklists for building Framework M (metadata-driven). Each phase builds upon the previous one.

Overview​

The framework development is divided into 12 phases:

  1. Phase 01: Core Kernel & Interfaces - Foundation with hexagonal architecture
  2. Phase 02: DocType Engine & Database - Metadata engine and dynamic schema mapping
  3. Phase 03: API Layer & Authorization - Auto-CRUD, permissions with RLS, and RPC
  4. Phase 04: Background Jobs & Events - Taskiq + NATS integration, event bus, and webhooks
  5. Phase 05: CLI & Developer Tools - m CLI tool for development and deployment
  6. Phase 06: Built-in DocTypes & Core Features - User, Role, Permission, File, and printing
  7. Phase 07: Studio (Code Generation UI) - Visual DocType builder with LibCST
  8. Phase 08: Workflows & Advanced Features - Pluggable workflows, DocType overrides, child tables
  9. Phase 09A: Frontend - Metadata-driven UI (Desk)
  10. Phase 09B: Documentation - Fundamentals, i18n, multi-tenancy docs, migration guides
  11. Phase 10: Production Readiness & Deployment - Performance, security, monitoring, and deployment
  12. Phase 11: Package Split & MX Pattern - Enable MX variants via package composition
  13. Phase 12: LLM-Ready Documentation - Auto-generated docs, screenshot automation, RAG/LLM corpus

How to Use These Checklists​

For Sequential Development​

Start with Phase 01 and work through each phase in order. Each phase assumes the previous phases are complete.

# Example workflow
1. Complete all tasks in phase-01-core-kernel.md
2. Verify the validation checklist at the end
3. Move to phase-02-doctype-engine.md
4. Repeat until all phases complete

For MVP-First Approach​

If you want to get a minimal viable product quickly:

MVP Phases (4-6 weeks):

  • Phase 01: Core Kernel & Interfaces
  • Phase 02: DocType Engine & Database
  • Phase 03: API Layer & Authorization
  • Phase 05: CLI & Developer Tools (basic commands only)

Post-MVP Enhancements:

  • Phase 04: Background Jobs & Events
  • Phase 06: Built-in DocTypes
  • Phase 07: Studio
  • Phase 08: Workflows & Advanced Features
  • Phase 09: Frontend
  • Phase 10: Production Readiness

For Parallel Development​

Some phases can be developed in parallel by different team members:

Parallel Track 1 (Backend):

  • Phase 01 → Phase 02 → Phase 03 → Phase 04

Parallel Track 2 (Tooling):

  • Phase 05 (CLI) → Phase 07 (Studio)

Parallel Track 3 (Frontend):

  • Phase 09 (after Phase 03 is complete)

Final Integration:

  • Phase 06 (Built-in DocTypes)
  • Phase 08 (Advanced Features)
  • Phase 10 (Production)

Key Principles​

Throughout all phases, remember these core principles:

1. No Monoliths​

Always define an interface (port) before an implementation (adapter). This keeps the architecture clean and testable.

2. Type Safety​

Use 100% type hints. Run mypy --strict regularly. This catches bugs early and improves developer experience.

3. No Global State​

Pass context via dependency injection. Avoid patterns like frappe.db or frappe.session.

4. Async All The Way​

Use async/await throughout. No blocking I/O in request handlers.

5. Test Everything​

Write tests as you build. Use pytest for unit tests, testcontainers for integration tests.

6. Additive Design​

New features are added as new protocols/adapters. Don't modify existing interfaces unless absolutely necessary.

Anti-Patterns to Avoid​

Learn from Frappe's mistakes:

❌ Global State - Don't use global variables for database, session, or user context ✅ Dependency Injection - Pass dependencies explicitly

❌ Monkey Patching - Don't modify core behavior via monkey patching ✅ Entrypoints - Use DI and entrypoints for extensibility

❌ Metadata in Database - Don't store DocType schemas in database ✅ Code-First - Define schemas as Pydantic models in code

❌ Custom Tooling - Don't build custom package managers or process managers ✅ Standard Tools - Use uv, docker-compose, kubernetes

❌ Blocking I/O - Don't use synchronous database calls ✅ Async/Await - Use asyncio throughout

❌ Tight Coupling - Don't import infrastructure in domain layer ✅ Hexagonal Architecture - Use ports and adapters

Progress Tracking​

Mark tasks as complete using this notation:

  • [ ] - Not started
  • [/] - In progress
  • [x] - Complete

Example:

- [x] Create project structure
- [/] Implement RepositoryProtocol
- [ ] Add tests

Getting Help​

If you get stuck on any phase:

  1. Review the Anti-Patterns section in each phase
  2. Check the Validation Checklist to ensure prerequisites are met
  3. Review the architecture diagrams in the main documentation
  4. Look at code examples in the implementation plan

Estimated Timeline​

Full Framework (all 12 phases):

  • Solo developer: 14-18 weeks
  • Small team (2-3): 10-14 weeks
  • Larger team (4+): 8-12 weeks

MVP (Phases 1-3, 5):

  • Solo developer: 4-6 weeks
  • Small team: 3-4 weeks
  • Larger team: 2-3 weeks

Documentation Sprint (Phase 12 only):

  • Solo developer: 1-2 weeks
  • With LLM assistance: 1 week

Success Criteria​

You'll know you're done when:

  • All phase validation checklists pass
  • mypy --strict passes with no errors
  • All tests pass (unit, integration, E2E)
  • Example apps work (TODO, CRM, etc.)
  • Documentation is complete and machine-readable
  • Load testing shows acceptable performance
  • Security scans show no critical issues
  • Framework can be installed via pip install framework-m
  • CLI tool m works for all commands
  • Studio can create and edit DocTypes
  • Frontend can render any DocType
  • m docs:generate produces API reference
  • Screenshot pipeline runs in CI
  • RAG corpus exports via m docs:export

Next Steps​

  1. Review the TODO.md for the full specification
  2. Start with Phase 01: Core Kernel
  3. Set up your development environment
  4. Begin implementing!