How soma-smart/framefox works
Project Type and Purpose
• Framefox is an open-source Python web framework built on FastAPI. It provides:
• A clean MVC architecture (Controllers, Templates, Repositories)
• A CLI tool for project scaffolding and code generation
• Core services (routing, DI container, ORM, forms, security, tasks, websockets, debugging, profiling)
• Integration with SQLModel, Pydantic, Alembic, Jinja2
• The repository also includes an Astro-based documentation site under docs/framefox, but the heart of the system is the framefox Python package plus its framefox/cli and framefox/core modules.
File Structure
• Top-level:
• .github, CI/CD workflows, linters, tests, docs site, README, license, pyproject.toml
• framefox/ – main Python package
• framefox/cli & framefox/terminal – interactive CLI commands and templates
• framefox/core – framework internals (kernel, DI, routing, controllers, events, middleware, ORM, security, forms, mail, tasks, websockets, templates, debugging/profiling)
• framefox/tests – unit and E2E tests
• Patterns:
• Layered MVC
• Service-provider / dependency-injection container
• Decorator-based routing & tasks
• Repository / Entity-Manager ORM
• Middleware pipeline
• Event dispatching/listening
• CLI code generators using Jinja2/Mako
README for Additional Insights
• Core features call out:
• FastAPI foundation → HTTP server and async support
• SQLModel & Pydantic → type-safe models and validation
• CLI → framefox create, framefox run, framefox database
• Security → CSRF, JWT, OAuth, firewall handlers
• Debugger & profiler UI → built-in error pages, profiling panels
• Background tasks → brokers (RabbitMQ, DB) and workers
• Encourages a standard MVC layout for user projects, but the framework itself must support and coordinate all moving parts.
Essential Architectural Elements
• Be detailed: show how each subsystem plugs into the Kernel
• Extension points (decorators, service definitions)
• Don’t over-abstract: include middleware, events, DI, CLI separately
• Both the runtime (request/task flows) and the developer experience (CLI)