README.md.jinja

# {{ project_name }}

{{ project_description }}

## Components

This Aegis Stack project includes the following components:

- **Backend**: FastAPI-based async web server
- **Frontend**: Flet-based Python UI framework
{%- if include_scheduler %}
- **Scheduler**: APScheduler-based async task scheduling
{%- endif %}
{%- if include_database %}
- **Database**: SQLite database with SQLModel ORM
{%- endif %}
{%- if include_cache %}
- **Cache**: Redis-based async caching
{%- endif %}

{% if include_auth or include_ai or include_comms or include_insights %}
## Services

{%- if include_auth %}
- **Auth**: JWT authentication with user management{% if include_oauth %} + GitHub/Google OAuth social login{% endif %}
{%- endif %}
{%- if include_ai %}
- **AI**: Multi-provider AI integration with PydanticAI
{%- endif %}
{%- if include_comms %}
- **Comms**: Email, SMS, and voice communications
{%- endif %}
{%- if include_insights %}
- **Insights**: Adoption metrics tracking (GitHub, PyPI, Plausible, Reddit)
{%- endif %}
{% endif %}

## Getting Started

### Prerequisites

- Python {{ python_version }}+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Installation

1. **Install dependencies:**
   ```bash
   uv sync                    # Core dependencies only
   # Or for development: uv sync --all-extras  (includes testing, linting, docs)
   ```

2. **Activate virtual environment:**
   ```bash
   source .venv/bin/activate
   ```

3. **Set up environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

{%- if include_database %}

4. **Set up database:**
   ```bash
   # Create data directory for SQLite database
   mkdir -p data

   # Database will be created automatically on first run
   # Default location: data/app.db
   ```

5. **Run the application:**
{%- else %}

4. **Run the application:**
{%- endif %}
   ```bash
   make serve
   ```

The application will be available at `http://127.0.0.1:8000`.

## Development

### Running Tests
```bash
make test
```

### Code Quality
```bash
make check  # Run linting, type checking, and tests
```

### CLI Commands

Your project gets its own CLI command **automatically installed** when first used - no setup required! 

```bash
# Health monitoring (auto-installs CLI if needed)
make health                     # Basic health check
make health-detailed            # Detailed component status
make health-json               # JSON output for scripts
make health-quick              # Quick healthy/unhealthy check

# Direct CLI usage (after first make command)
{{ project_slug }} health check              # Basic health check
{{ project_slug }} health check --detailed   # Detailed component status
{{ project_slug }} health check --json       # JSON output for scripts
{{ project_slug }} health quick              # Quick healthy/unhealthy check

# Explore all commands
{{ project_slug }} --help                    # See all available commands
{{ project_slug }} health --help             # See health subcommand options
```

**Environment Issues?** If CLI commands don't work:
```bash
# Ensure you're in the project's virtual environment
unset VIRTUAL_ENV               # Clear Docker contamination
source .venv/bin/activate       # Activate local venv
make health                     # This will auto-install CLI
# Or manually: make install-cli
```

### Documentation
```bash
make docs-serve  # Serve docs at http://localhost:8001/{{ project_slug }}/
```

## Docker

### Development
```bash
docker compose --profile dev up
```

### Production
```bash
docker compose --profile prod up
```

{%- if include_database %}

## Configuration

### Database Settings

The database component uses SQLite with the following default configuration:

```bash
# Environment variables (add to .env file)
DATABASE_URL=sqlite:///data/app.db          # Database file location
DATABASE_ENGINE_ECHO=false                  # Enable SQL query logging
```

### Database Usage

```python
from app.core.db import db_session
from sqlmodel import SQLModel, Field, select

# Define a model
class User(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    email: str

# Use the database
with db_session() as session:
    user = User(name="John Doe", email="john@example.com")
    session.add(user)
    # Auto-committed by context manager
```

{%- endif %}

{%- if include_oauth %}

### OAuth Social Login

GitHub and Google sign-in are wired up out of the box. Each provider
is enabled independently — leaving its client ID/secret blank turns
just that provider off (the route returns 503), so you can ship with
GitHub configured and add Google later.

**1. Create OAuth apps**

- **GitHub**: <https://github.com/settings/developers> → New OAuth App.
  - Authorization callback URL:
    `https://your-domain.example/api/v1/auth/oauth/github/callback`
  - Or for local dev:
    `http://localhost:8000/api/v1/auth/oauth/github/callback`
- **Google**: <https://console.cloud.google.com/apis/credentials> →
  Create Credentials → OAuth client ID → Web application.
  - Authorized redirect URI:
    `https://your-domain.example/api/v1/auth/oauth/google/callback`

**2. Set environment variables**

```bash
# OAuth client credentials (leave blank to disable a provider)
GITHUB_OAUTH_CLIENT_ID=...
GITHUB_OAUTH_CLIENT_SECRET=...
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...

# Secret for starlette's SessionMiddleware — Authlib stashes the
# OAuth state + PKCE verifier here between /start and /callback.
# MUST be overridden in any non-dev deployment.
OAUTH_SESSION_SECRET=replace-me-with-a-strong-random-string

# Optional: override the secure-flag heuristic. None (default) means
# off in dev, on otherwise. Set to false to run prod over HTTP without
# TLS — browsers refuse Secure cookies on insecure origins.
# SESSION_COOKIE_SECURE=
```

**3. Sign-in URLs**

- `GET /api/v1/auth/oauth/github/start?next=/dashboard`
- `GET /api/v1/auth/oauth/google/start?next=/dashboard`

The `?next=` parameter is honored only for same-origin paths. After a
successful callback the user is redirected to `next` (or `/app` by
default) with the JWT set in an HttpOnly `aegis_session` cookie. API
clients can keep using `Authorization: Bearer ...` — the cookie path
is parallel, not exclusive.

**4. Connection management**

Authenticated users can list and unlink their providers:

- `GET /api/v1/auth/oauth/connections`
- `DELETE /api/v1/auth/oauth/connections/{github|google}`

The disconnect route refuses to remove the last sign-in method to
avoid lock-out — set a password or link another provider first.

{%- endif %}

## Project Structure

```
{{ project_slug }}/
├── app/                    # Application code
│   ├── components/         # Component implementations
│   │   ├── backend/       # FastAPI backend
│   │   └── frontend/      # Flet frontend
{%- if include_scheduler %}
│   │   └── scheduler/     # APScheduler background tasks
{%- endif %}
│   ├── cli/               # CLI commands and health monitoring
│   ├── core/              # Core utilities
│   │   ├── config.py      # Environment-dependent configuration
│   │   ├── constants.py   # Immutable constants (12-Factor App)
{%- if include_database %}
│   │   ├── db.py          # Database connection and session management
{%- endif %}
│   │   └── log.py         # Structured logging
│   ├── entrypoints/       # Execution entry points
│   ├── integrations/      # App composition layer
{%- if _has_additional_components %}
│   └── services/          # Business logic services
{%- endif %}
├── tests/                 # Test suite
├── docs/                  # Documentation
├── docker-compose.yml     # Docker services
└── pyproject.toml        # Project configuration
```

---

Generated with [Aegis Stack](https://github.com/lbedner/aegis-stack)