# Code Standards

## General

- [Principle — Build minimal, focused automations; don't over-engineer]
- [Principle — Every workflow must have clear trigger, actions, and outcomes]
- [Principle — DRY: Define service packages once, reference everywhere]

## TypeScript

- [Rule — Use strict types for all financial data (cents, not dollars)]
- [Rule — Validate all incoming webhook data from Stripe/Calendly/Pipedrive]
- [Rule — Use proper error handling for automation failures]

## n8n Workflows

- [Rule — Each workflow must fit on one screen (max 10 nodes)]
- [Rule — Use meaningful node names: "Check Payment Status", not "Node 1"]
- [Rule — Always add error handling branches]
- [Convention — Trigger → Validate → Transform → Act → Notify

## API Integration

- [Rule — Use JSON over XML for all integrations]
- [Rule — Store API keys in environment variables only]
- [Rule — Log all API calls for debugging (no sensitive data)]
- [Rule — Implement retry logic with exponential backoff

## Dashboard (Metabase/Grafana)

- [Rule — Color-code metrics: green=good, red=bad, yellow=attention]
- [Rule — All charts must have clear titles and units]
- [Convention — Revenue metrics in USD, time in local timezone

## Data Flow Rules

- [Rule — Lead data flows: Typeform → Pipedrive → Notion → Calendar]
- [Rule — Financial data flows: Stripe → Dashboard → Reports]
- [Rule — Project data flows: Booking → Notion Template → GitHub → Client]

## File Organization

- `/workflows/` — n8n workflow definitions (JSON)
- `/integrations/` — API client configurations
- `/scripts/` — Utility scripts (stripe-sync, webhook-receivers)
- `/dashboards/` — Metabase/Grafana configuration
- `/templates/` — Email templates, proposal templates, project templates
- `/web/` — Static website files
- `/docs/` — Documentation and specs

## Testing

- [Rule — Test webhook receivers with ngrok during development
- [Rule — Validate financial calculations in test mode first
- [Rule — Run backup before major workflow changes]