Boo-Skeleton 🦴

Inspiration

We've all been there—staring at a blank screen, about to start a new backend project, knowing we'll spend the next few hours (or days) setting up the same boilerplate: database connections, CRUD endpoints, error handling, testing infrastructure, observability... It's exhausting and repetitive.

The inspiration for Boo-Skeleton came from a simple question: What if we could skip all that and jump straight to building features?

We wanted to create a tool that doesn't just generate code, but generates production-ready code with best practices baked in—proper architecture, comprehensive testing, full observability, and support for multiple databases. A tool that respects developers' time and lets them focus on what makes their project unique.

What it does

alt

Boo-Skeleton is a powerful CLI scaffolding tool that generates complete, production-ready FastAPI backends in seconds. Think of it as a "create-react-app" for FastAPI, but with superpowers.

One command creates:

✅ Complete FastAPI application with RESTful CRUD endpoints
✅ Clean layered architecture (routers → services → repositories → database)
✅ Your choice of database backend (SQLite, MongoDB, or PostgreSQL)
✅ Full OpenTelemetry observability (metrics, logs, traces)
✅ Pre-configured Grafana dashboard for monitoring
✅ Comprehensive test suite with property-based testing
✅ Virtual environment with all dependencies installed
✅ Configured .env file ready to run

Advanced features:

Topological Sorting: Automatically orders resources by dependencies using Kahn's algorithm
Circular Dependency Detection: Prevents invalid dependency chains before they cause issues
Cascade Delete: Intelligently removes dependent resources when parents are deleted
OpenTelemetry Integration: Full observability with metrics, structured logs, and distributed tracing
Grafana Dashboard: Pre-built dashboard for visualizing CRUD operations and performance

The result? You go from zero to a running, tested, monitored API in under 60 seconds.

How we built it

Technology Stack

CLI Framework:

Click: Command-line interface framework for intuitive commands
Rich: Beautiful terminal output with colors, progress bars, and formatted tables
Jinja2: Template engine for generating customized project files
PyYAML: Configuration management for database options and templates

Generated Application Stack:

FastAPI: Modern, fast web framework for building APIs
SQLAlchemy: SQL toolkit and ORM for relational databases
Motor: Async MongoDB driver for NoSQL support
Pydantic: Data validation using Python type annotations
OpenTelemetry: Observability framework for metrics, logs, and traces

Testing & Quality:

Pytest: Testing framework with async support
Hypothesis: Property-based testing for comprehensive coverage
Black, Ruff, MyPy: Code formatting, linting, and type checking
Pre-commit: Git hooks for automated quality checks

Observability Stack:

OpenTelemetry SDK: Instrumentation for metrics, logs, and traces
Prometheus: Metrics collection and storage
Grafana: Visualization and dashboarding
OTEL Collector: Unified telemetry pipeline

Grafana dashboard Alt

Applications we build with it

App 1 | Boo learner: Intelligent Course Learning Web Platform

Inspiration

Learning new skills often feels overwhelming because of complex dependency chains - you can't learn React without JavaScript, or machine learning without linear algebra. We wanted to create a system that automatically understands these relationships and guides learners through the optimal path. The inspiration came from seeing students struggle with course prerequisites and realizing that this is fundamentally a graph theory problem that could be solved elegantly with topological sorting.

What it does

boo-learner is an intelligent resource management platform that:

Tracks Learning Dependencies: Manages courses, tutorials, and learning resources with their prerequisite relationships
Detects Circular Dependencies: Prevents impossible learning paths by identifying circular prerequisites using Kahn's algorithm
Generates Optimal Learning Paths: Automatically sorts resources in topological order, ensuring you always learn prerequisites before advanced topics
Smart Search: Searches through resources while maintaining dependency order in results
Cascade Operations: Intelligently handles resource deletion with optional cascade to dependent resources
Real-time Validation: Validates dependency changes before committing to prevent breaking the learning graph

alt

Challenges we ran into

Circular Dependency Detection: Implementing efficient cycle detection in directed graphs was complex. We needed to not only detect cycles but also provide meaningful error messages showing the actual cycle path to users.
Async Database Operations: Managing async/await patterns with MongoDB Motor driver while maintaining clean code architecture required careful design of the repository pattern.
Cascade Delete Logic: Determining which resources to delete when cascading required building a reverse dependency graph and handling edge cases where multiple resources depend on the same prerequisite.
Topological Sort Edge Cases: Handling empty graphs, disconnected components, and resources with external dependencies (dependencies not in the current result set) required careful algorithm design.
Real-time Validation: Validating dependency changes before committing them to the database without race conditions required building temporary graphs and simulating the changes.

App 2 | Boo package manager: CLI Package dependency manger

Inspiration

Managing package dependencies is like solving a complex puzzle. We've all hit circular dependency errors or conflicts that break builds. Traditional package managers like pip lack intelligence for understanding dependency relationships. We wanted a smarter, collaborative approach - a package manager that detects circular dependencies before they break, automatically orders installations, and visualizes dependency trees beautifully.

What it does

Boo is a full-stack package management system with two components:

Backend API: FastAPI-based REST service featuring:

Smart dependency resolution using Kahn's topological sorting algorithm
Circular dependency detection and prevention
Cascade delete operations
Real-time validation before commits
MongoDB backend with async operations
CLI Tool: Developer-friendly command-line interface with:
- Rich terminal UI with colors and progress bars
- Dependency tree and graph visualization
- Lock files for reproducible installations
- Security vulnerability scanning
- Team collaboration and package syncing

Together, they provide intelligent, safe Python package management.

alt

Challenges we ran into

Robust Cycle Detection: Implementing Kahn's algorithm with DFS-based cycle detection was complex. We needed to not just detect cycles, but extract the exact cycle path for meaningful error messages.
Async Validation: Balancing async database operations with complex dependency validation without blocking the event loop or creating race conditions required careful service layer architecture.
Backend-Agnostic Design: Supporting multiple databases (MongoDB, PostgreSQL) meant abstracting operations behind repository interfaces and handling different data formats transparently.
CLI User Experience: Creating a powerful yet delightful terminal tool required balancing information density with readability. We used the Rich library to build a polished UI that feels modern.
Real-time Graph Validation: Ensuring every operation maintains a valid dependency graph required a comprehensive validation pipeline that prevents invalid states before they occur.

Overall Architecture Decisions for boo-skeleton

1. Separation of Concerns We separated the CLI tool from the application template, allowing independent development and testing of both components.

2. Repository Pattern The generated applications use an abstract repository pattern, making it trivial to swap database backends without changing business logic.

3. Template-Driven Generation We use Jinja2 templates for files that need customization (like .env and main.py) while copying static files directly for better performance.

4. Intelligent Dependency Management The topological sorting algorithm uses Kahn's algorithm (O(V+E) complexity) with cycle detection via depth-first search.

5. Full Observability by Default Every generated project includes OpenTelemetry instrumentation, making production monitoring a first-class citizen rather than an afterthought.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          Client Applications                         │
│                    (Web, Mobile, CLI, External APIs)                 │
└────────────────────────────────┬────────────────────────────────────┘
                                 │ HTTP/HTTPS
                                 │ REST API
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         FastAPI Application                          │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    API Layer (Routers)                        │  │
│  │  • Resource Endpoints  • Health Checks  • Documentation       │  │
│  └─────────────────────────────┬─────────────────────────────────┘  │
│                                │                                     │
│  ┌─────────────────────────────▼─────────────────────────────────┐  │
│  │                   Business Logic Layer (Services)             │  │
│  │  • Resource Service  • Topological Sort  • Validation         │  │
│  └─────────────────────────────┬─────────────────────────────────┘  │
│                                │                                     │
│  ┌─────────────────────────────▼─────────────────────────────────┐  │
│  │              Data Access Layer (Repositories)                 │  │
│  │  • Abstract Repository Interface                              │  │
│  │  • SQLAlchemy Implementation  • MongoDB Implementation        │  │
│  └─────────────────────────────┬─────────────────────────────────┘  │
└────────────────────────────────┼─────────────────────────────────────┘
                                 │
                    ┌────────────┴────────────┐
                    │                         │
                    ▼                         ▼
         ┌──────────────────┐      ┌──────────────────┐
         │  SQLite Database │      │ MongoDB Database │
         │   (Development)  │      │   (Production)   │
         └──────────────────┘      └──────────────────┘

Development Process

Research Phase: Studied existing scaffolding tools (create-react-app, Django startproject, Rails new) to understand what works
Architecture Design: Designed the layered architecture and repository pattern for maximum flexibility
Core Implementation: Built the CLI tool with interactive prompts and project generation
Database Support: Implemented SQLite, MongoDB, and PostgreSQL backends with consistent interfaces
Observability Integration: Added OpenTelemetry instrumentation and Grafana dashboards
Testing Infrastructure: Created comprehensive test suites with property-based testing
Polish & Documentation: Added beautiful CLI output, comprehensive docs, and examples

Challenges we ran into

1. Multi-Database Abstraction

Challenge: Supporting three different database backends (SQLite, MongoDB, PostgreSQL) with a single, consistent API.

Solution: We implemented the repository pattern with abstract base classes. Each database has its own repository implementation, but they all conform to the same interface. This required careful design to handle differences like:

SQLite's synchronous nature vs MongoDB's async-first approach
Relational vs document-based data models
Different query patterns and optimization strategies

2. Topological Sorting with Cycle Detection

Challenge: Implementing efficient topological sorting that handles circular dependencies gracefully.

Solution: We combined Kahn's algorithm for sorting with depth-first search for cycle detection. The tricky part was providing helpful error messages that show the entire cycle path, not just "cycle detected." We track the path during DFS traversal and return the full cycle when detected: A → B → C → A.

3. OpenTelemetry Integration Complexity

Challenge: OpenTelemetry has a steep learning curve with many moving parts (SDK, exporters, collectors, backends).

Solution: We created a simplified configuration system that:

Provides sensible defaults for development
Includes a one-command local observability stack
Pre-configures Prometheus, Grafana, and OTEL Collector
Includes a ready-to-import Grafana dashboard

The hardest part was getting trace context propagation working correctly across async operations.

4. Template Management

Challenge: Keeping the source application code in sync with the CLI tool's bundled templates.

Solution: We created a prepare_templates.py script that automatically syncs the src/ directory to the CLI's bundled source. This runs before every build and can be integrated into pre-commit hooks. It solved the problem of code duplication and version drift.

5. Virtual Environment Creation

Challenge: Reliably creating and activating virtual environments across different operating systems (Windows, macOS, Linux).

Solution: We use Python's built-in venv module and provide platform-specific activation instructions. The CLI detects the OS and shows the correct command. We also handle edge cases like:

Python not in PATH
Insufficient permissions
Existing virtual environments

6. Property-Based Testing

Challenge: Writing property-based tests that generate valid test data while avoiding false positives.

Solution: We created custom Hypothesis strategies that generate valid resource data (names, dependencies, etc.) while respecting constraints. The key was using assume() to filter out invalid cases rather than trying to generate only valid data.

7. Dependency Management

Challenge: Managing dependencies for both the CLI tool and the generated projects, ensuring compatibility across Python versions.

Solution: We use pip-tools for pinning dependencies and Dependabot for automated updates. The CLI has minimal dependencies (Click, Rich, Jinja2), while generated projects include everything needed for production (FastAPI, database drivers, OTEL, testing tools).

Accomplishments that we're proud of

1. 60-Second Setup

From pip install boo-skeleton to a running, tested, monitored API in under a minute. This isn't just fast—it's transformative for prototyping and hackathons.

2. Production-Ready by Default

Generated projects aren't toys—they include:

Proper error handling with custom exceptions
Comprehensive test suites (unit, integration, property-based)
Full observability with metrics, logs, and traces
Security best practices (environment variables, input validation)
Clean architecture that scales

3. Beautiful Developer Experience

The CLI uses Rich for gorgeous terminal output with:

Color-coded messages
Progress indicators
Formatted tables
Success/error icons
Helpful error messages

4. Intelligent Dependency Management

The topological sorting feature isn't just a gimmick—it solves real problems:

Prevents circular dependencies before they cause runtime errors
Enables cascade delete without orphaning resources
Provides clear error messages with full cycle paths
Handles complex dependency graphs efficiently

5. Observability as a First-Class Citizen

Most projects add monitoring as an afterthought. We made it default:

Every CRUD operation is instrumented
Structured logs with trace correlation
Pre-built Grafana dashboard
One-command local observability stack
Production-ready OTEL configuration

6. Multi-Database Support

Supporting three different database paradigms (relational, document, in-memory) with a single, consistent API is a significant achievement. Developers can switch databases by changing one environment variable.

7. Published to PyPI

Boo-Skeleton is available on PyPI, making it accessible to developers worldwide with a simple pip install.

What's next

Short-Term (Next 3 Months)

1. Additional Database Backends

MySQL/MariaDB support
Redis for caching layer
DynamoDB for serverless deployments

2. Authentication & Authorization

JWT token authentication
OAuth2 integration
Role-based access control (RBAC)
API key management

3. Enhanced CLI Features

boo-skeleton add-endpoint - Add new endpoints to existing projects
boo-skeleton add-model - Add new database models
boo-skeleton upgrade - Upgrade existing projects to latest template

4. More Observability Options

Jaeger integration for distributed tracing
Datadog exporter
New Relic integration
Custom metrics and dashboards

Medium-Term (6-12 Months)

5. Microservices Support

Generate multiple services with shared models
Service discovery integration
Inter-service communication patterns
API gateway configuration

6. Deployment Automation

Docker and Docker Compose generation
Kubernetes manifests
Terraform configurations
CI/CD pipeline templates (GitHub Actions, GitLab CI)

7. GraphQL Support

GraphQL schema generation
Strawberry or Ariadne integration
GraphQL + REST hybrid mode

8. Advanced Features

WebSocket support for real-time features
Background task processing (Celery, RQ)
Caching strategies (Redis, Memcached)
Rate limiting and throttling

Long-Term (12+ Months)

9. Plugin System

Community-contributed templates
Custom database backends
Custom middleware and extensions
Template marketplace

10. Web UI

Browser-based project generator
Visual dependency graph editor
Live preview of generated code
Interactive configuration

11. AI-Powered Features

Natural language project generation ("Create an e-commerce API with products and orders")
Intelligent endpoint suggestions based on models
Automated test generation
Performance optimization recommendations

12. Enterprise Features

Multi-tenancy support
Advanced security features (encryption at rest, audit logging)
Compliance templates (GDPR, HIPAA, SOC2)
Enterprise support and SLAs

Built with ❤️ for developers who want to build features, not boilerplate.

Built With

fast-api
html5
kiro
llm
python
rich

Boo skeleton

Boo-Skeleton 🦴

Inspiration

What it does

How we built it

Technology Stack

Applications we build with it

App 1 | Boo learner: Intelligent Course Learning Web Platform

Inspiration

What it does

Challenges we ran into

App 2 | Boo package manager: CLI Package dependency manger

Inspiration

What it does

Challenges we ran into

Overall Architecture Decisions for boo-skeleton

High-Level Architecture

Development Process

Challenges we ran into

1. Multi-Database Abstraction

2. Topological Sorting with Cycle Detection

3. OpenTelemetry Integration Complexity

4. Template Management

5. Virtual Environment Creation

6. Property-Based Testing

7. Dependency Management

Accomplishments that we're proud of

1. 60-Second Setup

2. Production-Ready by Default

3. Beautiful Developer Experience

4. Intelligent Dependency Management

5. Observability as a First-Class Citizen

6. Multi-Database Support

7. Published to PyPI

What's next

Short-Term (Next 3 Months)

Medium-Term (6-12 Months)

Long-Term (12+ Months)

Built With

Updates