Architecture Diagrams

The architecture diagrams in docs/assets/architecture/ are generated from the Python sources in this directory. Edit the source and re-render; don't edit the PNGs by hand.

Diagram	Source	Used in
System overview	`overview.py`	README, Architecture
API request routing	`api.py`	Architecture, Core API
Receipt scanning	`receipts.py`	Receipt Scanning
Expense chat	`expense_chat.py`	Expense Chat
Notifications	`notifications.py`	Architecture, Notifications
Build & delivery	`delivery.py`	CI
Startup investigation	`startup.py`	Core API, Architecture
OpenAI MCP	`openai_mcp.py`	OpenAI MCP, Architecture

Rendering

python3 -m venv /tmp/diagrams-venv
/tmp/diagrams-venv/bin/pip install -r docs/diagrams/requirements.txt
/tmp/diagrams-venv/bin/python docs/diagrams/render.py            # all diagrams
/tmp/diagrams-venv/bin/python docs/diagrams/render.py api        # one diagram

cairosvg needs the Cairo library (libcairo2 on Debian/Ubuntu, cairo on Fedora/Amazon Linux, brew install cairo on macOS). Labels are set in Noto Sans; install it so renders match.

Layout Rules

awsdiagram.py is a deliberately small renderer, not an auto-layout engine:

Nodes sit on each diagram's column/row grid (C0…, R1…), so related services line up.
Every connector lists its points explicitly, and every segment must be horizontal or vertical (the renderer rejects diagonals). Use port offsets such as node.r(12) when several connectors share one side of an icon.
Boundaries follow the AWS Architecture Icons group styles: AWS Cloud, then the Region, then tinted boxes for stacks or service categories. Actors outside AWS go in dashed external boxes.
After a layout change, look at the rendered PNG: no connector should cross an icon, a label or a group title.

When the infrastructure changes, update the diagram in the same pull request. apps/infra/main.ts lists the stacks, and cdk synth shows exactly which resources each one creates.

Icons

icons/ holds the official AWS Architecture Icons used here (July 2026 release, 48 px service and resource icons, 32 px group icons), copied unmodified under shorter names. To add one, download the current asset package from that page and copy the SVG in.