Skip to content

Commit 7ac22e9

Browse files
lbednerlbedner
authored
Merge pull request #640 from lbedner/updated-readme
Updated Readme
2 parents 85459f8 + 0daabc0 commit 7ac22e9

2 files changed

Lines changed: 105 additions & 66 deletions

File tree

‎README.md‎

Lines changed: 97 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@
77
[![Documentation](https://github.com/lbedner/aegis-stack/workflows/Deploy%20Documentation/badge.svg)](https://github.com/lbedner/aegis-stack/actions/workflows/docs.yml)
88
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
99
[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)
10-
10+
<br>
1111
[![Monthly Downloads](https://img.shields.io/pypi/dm/aegis-stack)](https://pypi.org/project/aegis-stack/)
1212
[![Total Downloads](https://static.pepy.tech/badge/aegis-stack)](https://pepy.tech/project/aegis-stack)
1313
[![PyPI - Top 10% 2026](https://img.shields.io/badge/PyPI-Top_10%25_2026-2ea043)](https://clickpy.clickhouse.com/dashboard/aegis-stack?min_date=2026-01-01&max_date=2026-12-31)
14-
14+
<br>
1515
[![Commits per Month](https://img.shields.io/github/commit-activity/m/lbedner/aegis-stack)](https://github.com/lbedner/aegis-stack/commits)
1616
[![Total Commits](https://img.shields.io/github/commit-activity/t/lbedner/aegis-stack)](https://github.com/lbedner/aegis-stack/commits)
1717
[![Last Commit](https://img.shields.io/github/last-commit/lbedner/aegis-stack)](https://github.com/lbedner/aegis-stack/commits)
@@ -24,72 +24,84 @@ No time for health checks, proper testing, or clean architecture. Just enough ti
2424

2525
![Aegis Stack Quick Start Demo](docs/images/aegis-demo.gif)
2626

27-
A production-ready FastAPI platform with modular components and a built-in control plane.
28-
29-
## Prerequisites
27+
**Ship FastAPI apps that grow with you.**
3028

31-
- **Python 3.11+**
32-
- **Docker & Docker Compose** - Required for the standard development workflow (`make serve`). Generated projects use Docker for consistent environments and service dependencies (Redis for workers, health monitoring, etc.).
29+
Aegis Stack scaffolds complete FastAPI applications with auth, payments, workers, AI, and a built-in control plane. Add what you need, remove what you don't, update when the framework improves.
3330

3431
## Quick Start
3532

3633
```bash
37-
# Run instantly without installation
38-
uvx aegis-stack init my-api
34+
uvx aegis-stack init my-api && cd my-api && make serve
35+
```
36+
37+
<details>
38+
<summary><strong>More examples</strong></summary>
3939

40-
# Create with user authentication
40+
```bash
41+
# Add user authentication out of the box
4142
uvx aegis-stack init user-app --services auth
4243

43-
# Create with background processing
44+
# Add background processing + scheduling
4445
uvx aegis-stack init task-processor --components scheduler,worker
4546

46-
# Start building
47-
cd my-api && make serve
47+
# Everything wired up at init
48+
uvx aegis-stack init full-app --services auth,payment,comms --components worker,scheduler
4849
```
4950

50-
> **CLI language support:** Use `aegis --lang zh` for Simplified Chinese (简体中文), or set `AEGIS_LANG=zh`.
51-
52-
**Installation alternatives:** See the [Installation Guide](https://lbedner.github.io/aegis-stack/installation/) for `uv tool install`, `pip install`, and development setup.
53-
54-
## Overseer - Your Application's Control Plane
55-
56-
![Overseer](docs/images/overseer-demo.gif)
57-
58-
<sub>[Live Demo: sector-7g.dev/dashboard](https://sector-7g.dev/dashboard/)</sub>
59-
60-
**[Overseer](https://lbedner.github.io/aegis-stack/overseer/)** is the embedded control plane that ships with every Aegis Stack project.
61-
62-
It gives you full runtime visibility into your system - components, services, infrastructure, and data flows - through a single dashboard. No external tooling, no vendor integrations, no setup.
63-
64-
Inspect worker queues, scheduled jobs, database schema and migrations, AI token usage, auth sessions - everything your application is doing, in real time.
65-
66-
Every Aegis project ships with its own control plane from day one.
67-
68-
## CLI - First-Class System Interface
69-
70-
![CLI Demo](docs/images/cli-demo.gif)
71-
72-
The Aegis CLI is a first-class interface to your running system.
51+
</details>
7352

74-
It goes beyond simple health checks, exposing rich, component-specific commands for inspecting and understanding your application from the terminal.
53+
> **CLI in 9 languages:** English, German, Spanish, French, Japanese, Korean, Russian, Simplified Chinese, Traditional Chinese. Use `aegis --lang <code>` or set `AEGIS_LANG`.
7554
76-
Query worker queues, scheduler activity, database state, AI usage, and service configuration, all without leaving the CLI.
77-
78-
The same system intelligence that powers Overseer and Illiana is available here, optimized for terminal workflows.
79-
80-
## Illiana - Optional System Operator
81-
82-
![Illiana Demo](docs/images/illiana-demo.gif)
83-
84-
When the AI service is enabled, Aegis exposes an additional interface: **Illiana**.
55+
**Installation alternatives:** See the [Installation Guide](https://lbedner.github.io/aegis-stack/installation/) for `uv tool install`, `pip install`, and development setup.
8556

86-
Illiana is a conversational interface that answers questions about your running system using live telemetry and optional RAG over your codebase.
57+
## Customizing Your Stack
58+
59+
**Components** are infrastructure pieces (database, workers, scheduler, cache). **Services** are business capabilities (auth, AI, payments, comms).
60+
61+
**Don't worry about what you pick today.** Add anything later with a single command, remove what you outgrow, no rework required.
62+
63+
### Components
64+
65+
| Component | What you get | |
66+
|---|---|---|
67+
| **[Core](https://lbedner.github.io/aegis-stack/components/)** | FastAPI + Flet + Typer | ![Always](https://img.shields.io/badge/-always_on-2ea043) |
68+
| **[Database](https://lbedner.github.io/aegis-stack/components/database/)** | Postgres or SQLite + SQLModel ORM | ![Optional](https://img.shields.io/badge/-optional-blue) |
69+
| **[Worker](https://lbedner.github.io/aegis-stack/components/worker/)** | Pluggable Arq, Taskiq, or Dramatiq | ![Optional](https://img.shields.io/badge/-optional-blue) |
70+
| **[Scheduler](https://lbedner.github.io/aegis-stack/components/scheduler/)** | APScheduler with persistent jobs | ![Optional](https://img.shields.io/badge/-optional-blue) |
71+
| **[Cache](https://lbedner.github.io/aegis-stack/components/)** | Redis for caching, sessions, pub/sub | ![Optional](https://img.shields.io/badge/-optional-blue) |
72+
| **[Ingress](https://lbedner.github.io/aegis-stack/components/ingress/)** | Traefik v3 reverse proxy with TLS | ![Optional](https://img.shields.io/badge/-optional-blue) |
73+
| **[Observability](https://lbedner.github.io/aegis-stack/components/observability/)** | Pydantic Logfire tracing + metrics + logging | ![Optional](https://img.shields.io/badge/-optional-blue) |
74+
| **[Inference](https://lbedner.github.io/aegis-stack/components/)** | Local AI models via Ollama | ![Optional](https://img.shields.io/badge/-optional-blue) |
75+
76+
### Services
77+
78+
| Service | What you get | |
79+
|---|---|---|
80+
| **[Auth](https://lbedner.github.io/aegis-stack/services/auth/)** | JWT sessions, RBAC, multi-tenant Organizations | ![Optional](https://img.shields.io/badge/-optional-blue) |
81+
| **[AI](https://lbedner.github.io/aegis-stack/services/ai/)** | Conversational agents, RAG, model catalog, TTS and STT (PydanticAI / LangChain across 7 providers) | ![Optional](https://img.shields.io/badge/-optional-blue) |
82+
| **[Comms](https://lbedner.github.io/aegis-stack/services/comms/)** | Transactional email (Resend) + SMS / voice (Twilio) | ![Optional](https://img.shields.io/badge/-optional-blue) |
83+
| **[Payments](https://lbedner.github.io/aegis-stack/services/payment/)** | Stripe checkout, subscriptions, refunds, disputes | ![Optional](https://img.shields.io/badge/-optional-blue) |
84+
| **[Insights](https://lbedner.github.io/aegis-stack/services/insights/)** | Adoption metrics across GitHub, PyPI, Plausible, Reddit | ![Optional](https://img.shields.io/badge/-optional-blue) |
85+
86+
Components compose into capabilities you didn't have to build:
87+
88+
```mermaid
89+
graph LR
90+
Auth[Auth] --> A[User-specific AI conversations]
91+
AI[AI] --> A
92+
AI --> B[Persistent history &<br/>token analytics]
93+
DB[(Database)] --> B
94+
AI --> C[Background AI pipelines]
95+
Worker[Worker] --> C
96+
Scheduler[Scheduler] --> D[Persistent job scheduling]
97+
DB --> D
98+
```
8799

88-
She is not required to use Aegis Stack, and nothing in the system depends on her being present. When enabled, she becomes another way, alongside the CLI and Overseer, to understand what your application is doing and why.
100+
[Components Docs →](https://lbedner.github.io/aegis-stack/components/) · [Services Docs →](https://lbedner.github.io/aegis-stack/services/)
89101

90102
## Your Stack Grows With You
91103

92-
**Your choices aren't permanent.** Start with what you need today, add components when requirements change, remove what you outgrow.
104+
**Your choices aren't permanent.** Start with what you need today, add when requirements change, remove what you outgrow.
93105

94106
```bash
95107
# Monday: Ship MVP
@@ -110,32 +122,51 @@ aegis update
110122

111123
| Starter | Add Later? | Remove Later? | Git Conflicts? |
112124
|-----------|------------|---------------|----------------|
113-
| **Others** | ❌ Locked at init | ❌ Manual deletion | ⚠️ High risk |
114-
| **Aegis Stack** | ✅ One command | ✅ One command | ✅ Auto-handled |
125+
| **Others** | Locked at init | Manual deletion | High risk |
126+
| **Aegis Stack** | One command | One command | Auto-handled |
115127

116128
![Component Evolution Demo](docs/images/aegis-evolution-demo.gif)
117129

118130
Most starters lock you in at `init`. Aegis Stack doesn't. See **[Evolving Your Stack](https://lbedner.github.io/aegis-stack/evolving-your-stack/)** for the complete guide.
119131

120-
## Available Components & Services
132+
## Overseer - Your Application's Control Plane
121133

122-
**Components** (infrastructure)
134+
![Overseer](docs/images/overseer-demo.gif)
123135

124-
- **Core** → FastAPI + Pydantic V2 + Uvicorn
125-
- **Database** → Postgres / SQLite
126-
- **Cache/Queue** → Redis
127-
- **Scheduler** → APScheduler
128-
- **Worker** → Arq / Taskiq / Dramatiq
136+
<sub>[Live Demo: sector-7g.dev/dashboard](https://sector-7g.dev/dashboard/)</sub>
129137

130-
**Services** (business logic)
138+
**[Overseer](https://lbedner.github.io/aegis-stack/overseer/)** is the embedded control plane that ships with every Aegis Stack project.
139+
140+
- Live health of every component and service in one view
141+
- Worker queues, scheduled jobs, recent runs
142+
- Database schema, tables, and migration state
143+
- AI token usage and conversation history
144+
- Auth sessions and user activity
145+
- No external tooling, no vendor integrations, no setup
146+
147+
## CLI - First-Class System Interface
148+
149+
![CLI Demo](docs/images/cli-demo.gif)
150+
151+
The Aegis CLI is a first-class interface to your running system. Not just a health check, but a full inspection layer.
152+
153+
- Component-aware commands for every running subsystem
154+
- Inspect worker queues, scheduler runs, database state
155+
- Query AI usage, auth sessions, service configuration
156+
- Same data Overseer sees, terminal-native
157+
- Built into every generated project, no extra installs
158+
159+
## Illiana - Optional System Operator
160+
161+
![Illiana Demo](docs/images/illiana-demo.gif)
131162

132-
- **AI** → PydanticAI / LangChain
133-
- **Auth** → JWT authentication
134-
- **Comms** → Resend + Twilio
135-
- **Insights** → Adoption metrics (GitHub, PyPI, Plausible) *(experimental)*
136-
- **Payment** → Stripe checkout, subscriptions, refunds, disputes *(experimental)*
163+
When the AI service is enabled, Aegis exposes an additional interface: **Illiana**, a conversational operator over your running system.
137164

138-
[Components Docs →](https://lbedner.github.io/aegis-stack/components/) | [Services Docs →](https://lbedner.github.io/aegis-stack/services/)
165+
- Ask questions in plain language about live system state
166+
- Backed by live telemetry from Overseer and the CLI
167+
- Optional RAG over your codebase for code-aware answers
168+
- Opt-in: only available when the AI service is on
169+
- Nothing in the stack depends on her being there
139170

140171
## Learn More
141172

@@ -154,4 +185,4 @@ No reinventing the wheel. Just the tools you already know, pre-configured and re
154185

155186
Aegis Stack respects your expertise. No custom abstractions or proprietary patterns to learn. Pick your components, get a production-ready foundation, and build your way.
156187

157-
Aegis gets out of your way so you can get started.
188+
Aegis gets out of your way so you can get started.

‎docs/stylesheets/custom.css‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
11
/* Custom styles for Aegis Stack documentation */
22

3+
/* Alternating row striping for tables (matches GitHub) */
4+
.md-typeset table:not([class]) tbody tr:nth-child(even) {
5+
background-color: rgba(255, 255, 255, 0.025);
6+
}
7+
[data-md-color-scheme="default"] .md-typeset table:not([class]) tbody tr:nth-child(even) {
8+
background-color: rgba(0, 0, 0, 0.025);
9+
}
10+
311
/* Make all tables stretch to full width */
412
.md-typeset table {
513
width: 100%;

0 commit comments

Comments
 (0)