Merge pull request #33 from lbedner/database-documentation

Database Documentation

Author: lbedner

CLAUDE.md

@@ -11,6 +11,20 @@ The architecture follows this pattern:
 - **Generated Projects**: Full-stack containerized applications created by the CLI
 - **Templates**: Cookiecutter templates that define generated project structure
 
+## Release Status: v0.1.0 (LIVE on PyPI!)
+
+**First Official Release** - August 2024
+- ✅ **CLI Tool**: Published to PyPI as `aegis-stack`
+- ✅ **Database Component**: SQLite + SQLModel ORM with health monitoring
+- ✅ **Foundation Stack**: FastAPI backend + Flet frontend + Docker containerization
+- ✅ **Worker Component**: arq + Redis for background job processing
+- ✅ **Scheduler Component**: APScheduler for scheduled tasks
+- ✅ **Documentation**: Progressive documentation philosophy - grows with real implementations
+
+**Install**: `pip install aegis-stack`
+**PyPI**: https://pypi.org/project/aegis-stack/
+**GitHub Release**: https://github.com/lbedner/aegis-stack/releases/tag/v0.1.0
+
 ## Development Commands
 
 This project uses `uv` for dependency management and a `Makefile` for CLI development tasks.

README.md

@@ -1,14 +1,14 @@
 # Aegis Stack 🛡️
 
+**Build production-ready Python applications with your chosen components.**
+
 [![CI](https://github.com/lbedner/aegis-stack/workflows/CI/badge.svg)](https://github.com/lbedner/aegis-stack/actions/workflows/ci.yml)
 [![Documentation](https://github.com/lbedner/aegis-stack/workflows/Deploy%20Documentation/badge.svg)](https://github.com/lbedner/aegis-stack/actions/workflows/docs.yml)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 
-**Build production-ready Python applications with your chosen components.**
-
 Aegis Stack is a CLI-driven framework for creating custom Python applications. Select exactly the components you need - no bloat, no unused dependencies.
 
-## 🚀 Quick Start
+## Quick Start
 
 ```bash
 # Install
@@ -24,45 +24,43 @@ aegis init task-processor --components scheduler,worker
 cd my-project && uv sync && source .venv/bin/activate && make run-local
 ```
 
-## 🧩 Available Components
+## Available Components
 
 | Component | Purpose | Status |
 |-----------|---------|--------|
-| **Core** (FastAPI + Flet) | Web API + Frontend | ✅ **Included** |
+| **Core** (FastAPI + Flet) | Web API + Frontend | ✅ **Always Included** |
+| **Database** | SQLite + SQLModel ORM | ✅ **Available** |
 | **Scheduler** | Background tasks, cron jobs | ✅ **Available** |
-| **Worker** | Async task queues, job processing | ✅ **Available** |
-| **Database** | PostgreSQL + SQLAlchemy + Alembic | 🚧 **Coming Soon** |
+| **Worker** | Async task queues (arq + Redis) | 🧪 **Experimental** |
 | **Cache** | Redis caching and sessions | 🚧 **Coming Soon** |
 
-## What You Get
-
-- **FastAPI backend** with automatic API documentation
-- **Flet frontend** with health dashboard  
-- **CLI management** with health monitoring commands
-- **Worker queues** with async task processing and load testing
-- **Production ready** with structured logging and containerization
-- **Async-first** architecture for high-concurrency workloads
+## See It In Action
 
-## 📱 System Health Dashboard
+### System Health Dashboard
 
 ![System Health Dashboard](docs/images/dashboard-light.png#only-light)
 ![System Health Dashboard](docs/images/dashboard-dark.png#only-dark)
 
 Real-time monitoring with component status, health percentages, and cross-platform deployment (web, desktop, mobile).
 
-## 📚 Learn More
+### CLI Health Monitoring
+
+![CLI Health Check](docs/images/cli_health_check.png)
+
+Rich terminal output showing detailed component status, health metrics, and system diagnostics.
+
+## Learn More
 
 - **[📖 CLI Reference](docs/cli-reference.md)** - Complete command reference
 - **[🏗️ Components](docs/components/index.md)** - Deep dive into available components  
 - **[🧠 Philosophy](docs/philosophy.md)** - Architecture and design principles
 
-## Development Commands
+## For The Veterans
 
-```bash
-make run-local    # Start development server
-make test         # Run test suite  
-make check        # Run all quality checks
-make docs-serve   # Serve documentation
-```
+![Ron Swanson](docs/images/ron-swanson.gif)
+
+No magic. No reinventing the wheel. Just the tools you already know, pre-configured and ready to compose.
+
+Aegis Stack respects your expertise. We maintain existing standards - FastAPI for APIs, SQLModel for databases, arq for workers. No custom abstractions or proprietary patterns to learn. Pick your components, get a production-ready foundation, and build your way.
 
-Built on FastAPI, Flet, Typer, and other open-source tools.
+The framework gets out of your way so you can get started.

aegis/core/CLAUDE.md

@@ -36,6 +36,12 @@ COMPONENTS: dict[str, ComponentSpec] = {
         description="Scheduled task execution with APScheduler",
         type=ComponentType.INFRASTRUCTURE,
     ),
+    "database": ComponentSpec(
+        name="database",
+        description="SQLite database with SQLModel ORM",
+        type=ComponentType.INFRASTRUCTURE,
+        requires=[],  # Standalone component
+    ),
 }
 ```
 
@@ -171,6 +177,12 @@ class TemplateGenerator:
                 "tests/services/test_worker_health_registration.py",
             ])
 
+        if "database" in self.components:
+            files.extend([
+                "app/core/db.py",
+                "tests/conftest.py",  # Database testing fixtures
+            ])
+        
         return sorted(files)
 ```
 

aegis/templates/CLAUDE.md

@@ -48,7 +48,8 @@ aegis/templates/cookiecutter-aegis-project/
     "version": "0.1.0",
     "python_version": "3.11",
     "include_scheduler": "no",
-    "include_worker": "no"
+    "include_worker": "no",
+    "include_database": "no"
 }
 ```
 
@@ -73,6 +74,10 @@ aegis/templates/cookiecutter-aegis-project/
 {% if cookiecutter.include_worker == "yes" %}
 # Worker-specific content
 {% endif %}
+
+{% if cookiecutter.include_database == "yes" %}
+# Database-specific content
+{% endif %}
 ```
 
 ### Conditional Files
@@ -102,6 +107,11 @@ dependencies = [
     "arq>=0.26.1",
     "redis>=5.2.1",
 {% endif %}
+{% if cookiecutter.include_database == "yes" %}
+    "sqlmodel>=0.0.14",
+    "sqlalchemy>=2.0.0", 
+    "aiosqlite>=0.19.0",
+{% endif %}
 ]
 ```
 
@@ -122,6 +132,11 @@ if "{{ cookiecutter.include_new_component }}" != "yes":
     remove_dir("app/components/new_component")
     remove_file("app/entrypoints/new_component.py")
     remove_file("tests/components/test_new_component.py")
+
+# Database component logic
+if "{{ cookiecutter.include_database }}" != "yes":
+    remove_file("app/core/db.py")
+    remove_sections_from_conftest("tests/conftest.py", ["database"])
 ```
 
 ### File Removal Patterns

docs/CLAUDE.md

@@ -4,6 +4,22 @@ This guide covers documentation standards and patterns for Aegis Stack component
 
 ## Documentation Standards
 
+### Progressive Documentation Philosophy (v0.1.0+)
+
+**Architecture-First Documentation**: Documentation should trail real implementations, not lead them.
+
+**Core Principles:**
+- **Lean Start**: Begin with infrastructure capabilities and basic setup
+- **Real Examples**: Add concrete examples only after building actual services  
+- **Avoid Hypotheticals**: No theoretical User/Post models until auth exists
+- **Progressive Enhancement**: Documentation grows as the system evolves
+
+**Implementation Strategy:**
+- **Database Component**: Infrastructure setup only, real patterns come with User service
+- **Worker Component**: Task execution patterns, real examples with scheduler integration  
+- **Scheduler Component**: Basic scheduling, real patterns with job persistence
+- **Integration Docs**: Added when multiple components work together
+
 ### Components Documentation (Voltron Philosophy)
 
 **Components represent swappable capabilities** (web serving, scheduling, caching) with multiple implementation choices.
@@ -13,8 +29,11 @@ This guide covers documentation standards and patterns for Aegis Stack component
 docs/components/
 ├── index.md           # Overview of all components
 ├── webserver.md       # Web server capability (FastAPI impl)
+├── database.md        # Database capability (SQLite/SQLModel impl) - v0.1.0
 ├── frontend.md        # Frontend capability (Flet impl)  
-└── scheduling.md      # Future: Scheduling capability (APScheduler/schedule)
+├── worker.md          # Worker capability (arq/Redis impl)
+├── scheduler.md       # Scheduler capability (APScheduler impl)
+└── future/            # Future components as needs emerge
 ```
 
 **Component Documentation Pattern:**