# Architecture Context

## Stack

| Layer | Technology | Role |
| ----- | ---------- | ---- |
| Framework | Astro.js + TypeScript | Static site generator with API endpoints for webhooks |
| UI | Tailwind CSS + Minimal Components | Clean, conversion-focused interface |
| Automation | n8n Self-hosted | Workflow orchestration engine |
| Payments | Stripe | Payment processing, billing, quotes |
| Booking | Calendly | Scheduling and calendar integration |
| CRM | Pipedrive | Lead and pipeline management |
| Projects | Notion API | Project templates and tracking |
| Analytics | Metabase | KPI dashboard and business intelligence |
| Hosting | Self-hosted VPS (Hetzner) | All services on single server |

## System Boundaries

- `/web/` — Public website, service pages, booking funnel
- `/workflows/` — n8n workflow definitions (lead, booking, invoicing)
- `/integrations/` — Stripe, Pipedrive, Calendly, Notion API clients
- `/dashboards/` — Metabase configuration and SQL queries
- `/scripts/` — Webhook receivers, data sync utilities
- `/templates/` — Email, proposal, and project templates

## Storage Model

- **Database (SQLite)**: Financial records, client data, project metadata
- **File Storage (local)**: Website assets, generated contracts, invoices
- **Redis**: n8n workflow state, message queues
- **Notion**: Project templates, client documentation

## Auth and Access Model

- **Public website**: No auth required, booking requires Calendly account
- **n8n dashboard**: Basic auth with environment-stored credentials
- **Dashboard**: Admin access via IP whitelist + password
- **No user accounts needed**: System is service-based, not customer-facing

## Invariants

1. All financial transactions must be logged with Stripe event ID
2. Lead data must flow: Typeform → Pipedrive → Notion → Calendar
3. Invoices must be generated only after milestone completion
4. Maintenance billing must auto-renew on the 1st of each month
5. All webhook endpoints must verify signature authenticity
6. Dashboard data must be no more than 1 hour stale

## Architecture Diagram

```
[Website Visitor]
       ↓
[Calendly Booking] ←→ [Pipedrive CRM]
       ↓                     ↓
[Typeform Qualification]   [Notion Projects]
       ↓                     ↓
    [n8n Workflows] ←→ [Stripe Billing]
       ↓                     ↓
   [Metabase Dashboard] → [Email Sequences]
```