Merge pull request #173 from lbedner/service-documentation

Service Documentation

Author: lbedner

README.md

@@ -3,7 +3,7 @@
   <img src="docs/images/aegis-manifesto.png" alt="Aegis Stack" width="400">
 </picture>
 
-**Build production-ready Python applications with your chosen components.**
+**Build production-ready Python applications with your chosen components and services.**
 
 [![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)
@@ -17,11 +17,14 @@ Aegis Stack is a CLI-driven framework for creating custom Python applications. S
 # Run instantly without installation
 uvx aegis-stack init my-api
 
-# Create with background processing  
+# Create with user authentication
+uvx aegis-stack init user-app --services auth
+
+# Create with background processing
 uvx aegis-stack init task-processor --components scheduler,worker
 
 # Start building
-cd my-api && uv sync && cp .env.example .env && make run-local
+cd my-api && uv sync && cp .env.example .env && make server
 ```
 
 ## Installation
@@ -45,8 +48,9 @@ pip install aegis-stack
 aegis init my-project
 ```
 
-## Available Components
+## Available Components & Services
 
+### Infrastructure Components
 | Component | Purpose | Status |
 |-----------|---------|--------|
 | **Core** (FastAPI + Flet) | Web API + Frontend | ✅ **Always Included** |
@@ -55,6 +59,12 @@ aegis init my-project
 | **Worker** | Async task queues (arq + Redis) | 🧪 **Experimental** |
 | **Cache** | Redis caching and sessions | 🚧 **Coming Soon** |
 
+### Business Services
+| Service | Purpose | Status |
+|---------|---------|--------|
+| **Auth** | User authentication & JWT | ✅ **Available** |
+| **AI** | OpenAI integration | 🚧 **Coming Soon** |
+
 ## See It In Action
 
 ### System Health Dashboard
@@ -72,7 +82,8 @@ Rich terminal output showing detailed component status, health metrics, and syst
 ## Learn More
 
 - **[📖 CLI Reference](docs/cli-reference.md)** - Complete command reference
-- **[🏗️ Components](docs/components/index.md)** - Deep dive into available components  
+- **[🏗️ Components](docs/components/index.md)** - Deep dive into available components
+- **[🔧 Services](docs/services/index.md)** - Business services (auth, AI)
 - **[🧠 Philosophy](docs/philosophy.md)** - Architecture and design principles
 
 ## For The Veterans

aegis/commands/init.py

@@ -153,10 +153,6 @@ def init_command(
             interactive_project_selection()
         )
 
-        # Merge interactively selected services with any already specified
-        if interactive_services:
-            selected_services = list(set(selected_services + interactive_services))
-
         # Resolve dependencies for interactively selected components
         if selected_components:
             # Clean component names for dependency resolution (remove engine info)
@@ -179,22 +175,8 @@ def init_command(
             if auto_added:
                 typer.echo(f"\n📦 Auto-added dependencies: {', '.join(auto_added)}")
 
-        # Resolve service dependencies for interactively selected services
-        if interactive_services:
-            service_components, _ = ServiceResolver.resolve_service_dependencies(
-                interactive_services
-            )
-            # Merge service-required components with existing components
-            all_components = list(set(selected_components + service_components))
-            if service_components:
-                new_components = [
-                    c for c in service_components if c not in selected_components
-                ]
-                if new_components:
-                    typer.echo(
-                        f"\n🔧 Auto-added components for services: {', '.join(new_components)}"
-                    )
-            selected_components = all_components
+        # Merge interactively selected services with any already selected services
+        selected_services = list(set(selected_services + interactive_services))
 
     # Create template generator with scheduler backend context
     template_gen = TemplateGenerator(
@@ -291,7 +273,7 @@ def init_command(
         typer.echo(f"   cd {project_path.resolve()}")
         typer.echo("   uv sync")
         typer.echo("   cp .env.example .env")
-        typer.echo("   make run-local")
+        typer.echo("   make server")
 
     except ImportError:
         typer.echo("❌ Error: cookiecutter not installed", err=True)

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/README.md.j2

@@ -61,7 +61,7 @@ This Aegis Stack project includes the following components:
 4. **Run the application:**
 {%- endif %}
    ```bash
-   make run-local
+   make server
    ```
 
 The application will be available at `http://127.0.0.1:8000`.

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/cli/health.py.j2

@@ -119,7 +119,7 @@ async def get_health_data(
             raise ConnectionError(
                 f"Cannot connect to API server at {base_url}. "
                 "Make sure the application is running with "
-                "'make run-local' or 'make run-dev'."
+                "'make server' or 'make run-dev'."
             ) from None
         except httpx.TimeoutException:
             raise TimeoutError(

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/clean-validation/README.md.j2

@@ -48,7 +48,7 @@ This Aegis Stack project includes the following components:
 
 5. **Run the application:**
    ```bash
-   make run-local
+   make server
    ```
 
 The application will be available at `http://127.0.0.1:8000`.

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/tests/api/test_scheduler_endpoints.py.j2

@@ -145,7 +145,7 @@ class TestSchedulerEndpoints:
 
             if tasks:
                 # Test detail endpoint with first available job
-                job_id = tasks[0]["id"]
+                job_id = tasks[0]["job_id"]
                 url = f"/api/v1/scheduler/jobs/{job_id}"
                 detail_response = await async_client.get(url)
 

docs/cli-reference.md

@@ -18,27 +18,34 @@ aegis init PROJECT_NAME [OPTIONS]
 **Options:**
 
 - `--components, -c TEXT` - Comma-separated list of components (scheduler,worker,database,cache)
+- `--services, -s TEXT` - Comma-separated list of services (auth,payment,ai,analytics)
 - `--interactive / --no-interactive, -i / -ni` - Use interactive component selection (default: interactive)
 - `--force, -f` - Overwrite existing directory if it exists
-- `--output-dir, -o PATH` - Directory to create the project in (default: current directory) 
+- `--output-dir, -o PATH` - Directory to create the project in (default: current directory)
 - `--yes, -y` - Skip confirmation prompt
 
 **Examples:**
 ```bash
 # Simple API project
 aegis init my-api
 
-# Background processing system with scheduler  
+# Background processing system with scheduler
 aegis init task-processor --components scheduler
 
 # Background processing system with worker
 aegis init task-processor --components worker
 
-# Full stack (future)
-aegis init webapp --components scheduler,worker,database,cache
+# User authentication system
+aegis init user-app --services auth
+
+# Full business application
+aegis init business-app --services auth,payment --components worker
 
 # Non-interactive with custom location
-aegis init my-app --components scheduler --no-interactive --output-dir /projects --yes
+aegis init my-app --services auth --no-interactive --output-dir /projects --yes
+
+# Combined services and components (must include auth's required components)
+aegis init full-stack --services auth --components database,scheduler,worker
 ```
 
 **Available Components:**
@@ -47,9 +54,65 @@ aegis init my-app --components scheduler --no-interactive --output-dir /projects
 |-----------|--------|-------------|
 | `scheduler` | ✅ Available | APScheduler-based async task scheduling |
 | `worker` | ✅ Available | Pure arq worker with multiple queues for background processing |
-| `database` | 🚧 Coming Soon | SQLAlchemy + asyncpg for PostgreSQL |
+| `database` | ✅ Available | SQLite database with SQLModel ORM |
 | `cache` | 🚧 Coming Soon | Redis-based async caching |
 
+**Available Services:**
+
+| Service | Status | Description | Auto-Added Components |
+|---------|--------|-------------|---------------------|
+| `auth` | ✅ Available | User authentication and authorization with JWT tokens | database *(backend+frontend always included)* |
+| `ai` | 🚧 Coming Soon | OpenAI integration for AI features | worker *(backend+frontend always included)* |
+
+**Service Auto-Resolution:**
+
+When you select services, required components are automatically included:
+
+```mermaid
+graph LR
+    Service["--services auth"] --> Core["backend + frontend<br/>Always included"]
+    Service --> Database["database component<br/>Auto-added by auth"]
+    Service --> AuthFiles["Auth API routes + User models"]
+
+    style Service fill:#e8f5e8
+    style Core fill:#e8f4fd
+    style Database fill:#fff3e0
+    style AuthFiles fill:#f1f8e9
+```
+
+**Important CLI Behavior:**
+- `backend` and `frontend` components are always included in every project
+- **Interactive mode** (`aegis init project`): Services auto-add their required components
+- **Non-interactive mode** (`--components` specified): You must explicitly include all required components
+- Example: `--services auth` requires `--components database` (auth won't auto-add it)
+
+## aegis services
+
+List available services and their dependencies.
+
+**Usage:**
+```bash
+aegis services
+```
+
+**Example Output:**
+```
+🔧 AVAILABLE SERVICES
+========================================
+
+🔐 Authentication Services
+----------------------------------------
+  auth         - User authentication and authorization with JWT tokens
+               Requires components: backend, database
+
+💰 Payment Services
+----------------------------------------
+  No services available yet.
+
+🤖 AI & Machine Learning Services
+----------------------------------------
+  No services available yet.
+```
 
 ## aegis version
 
@@ -118,7 +181,7 @@ cd my-project
 uv sync                    # Install dependencies and create virtual environment
 source .venv/bin/activate  # Activate virtual environment (important!)
 cp .env.example .env       # Configure environment
-make run-local             # Start development server
+make server               # Start development server
 make test                  # Run test suite
 make check                 # Run all quality checks
 ```

docs/components/index.md

@@ -1,6 +1,12 @@
 # Components Overview
 
-Components are the building blocks of your Aegis Stack application. Each component provides a specific capability like API serving, background tasks, or data persistence.
+Components are the **infrastructure building blocks** of your Aegis Stack application. Each component provides a specific capability like API serving, background tasks, or data persistence.
+
+!!! info "Components vs Services"
+    **Components** = Infrastructure capabilities (database, workers, scheduling)
+    **Services** = Business functionality (auth, payments, AI integrations)
+
+    See **[Services Overview](../services/index.md)** for business-level features.
 
 > 💡 **New to Aegis Stack?** See the [Philosophy Guide](../philosophy.md) for complete component design principles.
 
@@ -14,14 +20,20 @@ The interactive CLI guides you through component choices and explains integratio
 # Basic web application (FastAPI + Flet)
 aegis init my-project
 
+# Add user authentication (auto-includes database)
+aegis init user-app --services auth
+
 # Add background task scheduling
 aegis init scheduled-app --components scheduler
 
 # Add job persistence + automatic backup job
 aegis init persistent-jobs --components scheduler,database
 
 # Full async task processing
-aegis init task-processor --components worker,redis
+aegis init task-processor --components worker
+
+# Business app with auth and background processing
+aegis init business-app --services auth --components worker,scheduler
 ```
 
 ## Component Architecture

docs/index.md

@@ -18,11 +18,14 @@ pip install aegis-stack
 # Create a simple API
 aegis init my-api
 
-# Create with background processing  
+# Create with user authentication
+aegis init user-app --services auth
+
+# Create with background processing
 aegis init task-processor --components scheduler,worker
 
 # Start building
-cd my-project && uv sync && source .venv/bin/activate && make run-local
+cd my-project && uv sync && source .venv/bin/activate && make server
 ```
 
 ## 🔨 Know What You're Doing?
@@ -32,13 +35,14 @@ cd my-project && uv sync && source .venv/bin/activate && make run-local
 **"I know more than you."** - Got it. Here's what you can build with:
 
 ```bash
-aegis init my-project --components worker,scheduler,database
+aegis init my-project --services auth --components worker,scheduler
 ```
 
 Your stack. Your rules. No hand-holding.
 
-## 🧩 Available Components
+## 🧩 Available Components & Services
 
+### Infrastructure Components
 | Component | Purpose | Status |
 |-----------|---------|--------|
 | **Core** (FastAPI + Flet) | Web API + Frontend | ✅ **Always Included** |
@@ -47,6 +51,12 @@ Your stack. Your rules. No hand-holding.
 | **Worker** | Async task queues (arq + Redis) | 🧪 **Experimental** |
 | **Cache** | Redis caching and sessions | 🚧 **Coming Soon** |
 
+### Business Services
+| Service | Purpose | Status |
+|---------|---------|--------|
+| **Auth** | User authentication & JWT | ✅ **Available** |
+| **AI** | OpenAI integration | 🚧 **Coming Soon** |
+
 ## What You Get
 
 - **FastAPI backend** with automatic API documentation
@@ -65,13 +75,14 @@ Real-time monitoring with component status, health percentages, and cross-platfo
 ## 📚 Learn More
 
 - **[📖 CLI Reference](cli-reference.md)** - Complete command reference
-- **[🏗️ Components](components/index.md)** - Deep dive into available components  
+- **[🏗️ Components](components/index.md)** - Infrastructure components (database, worker, scheduler)
+- **[🔧 Services](services/index.md)** - Business services (auth, payment, AI)
 - **[🧠 Philosophy](philosophy.md)** - Architecture and design principles
 
 ## Development Commands
 
 ```bash
-make run-local    # Start development server
+make server       # Start development server
 make test         # Run test suite  
 make check        # Run all quality checks
 make docs-serve   # Serve documentation