Platform Architecture
Architecture Overview
Section titled “Architecture Overview”GrowthOS is built around a central event bus that connects every growth module to a shared data layer and analytics backbone. Modules never talk to each other directly — they emit events, and the platform routes those events to the right destinations.
Every event follows a canonical schema, gets persisted to PostgreSQL for operational use, and forwarded to PostHog for analytics, feature flags, and experimentation.
Tech Stack Summary
Section titled “Tech Stack Summary”- Runtime: Node.js or Python
- Framework: Express or FastAPI
- Database: PostgreSQL with row-level security for multi-tenancy
- Event Streaming: Kafka or RedPanda (self-hosted)
- Workflow Orchestration: Temporal.io for durable, long-running workflows
- Email Delivery: SES or Postmark
- Dashboard: React (admin and tenant dashboards)
- Embeddable Widgets: Custom Web Components (framework-agnostic)
- Build Tooling: Vite
- Component Development: Storybook
- Cloud: AWS (VPC, RDS, ECS/K8s, CloudFront)
- Analytics: PostHog self-hosted on ClickHouse
- CI/CD: GitHub Actions
- Observability: Prometheus + Grafana
Build vs Integrate Decision Matrix
Section titled “Build vs Integrate Decision Matrix”Every component in GrowthOS goes through a deliberate build-or-buy evaluation. The guiding principle: build what creates defensible IP, integrate proven FOSS, buy commodity infrastructure.
| Component | Decision | Rationale |
|---|---|---|
| Contact graph | Build | Core IP — unified identity is the moat |
| Event bus | Self-host | RedPanda (Kafka-compatible, lower ops overhead) |
| PostgreSQL | Self-host | Operational data store with RLS |
| Temporal.io | Self-host | Workflow orchestration for sequences and campaigns |
| Analytics | Integrate | PostHog FOSS edition — proven at scale |
| Feature flags | Integrate | PostHog feature flags — already in the stack |
| Email automation | Evaluate | Mautic or Laudspeaker (FOSS options) |
| Notifications | Evaluate | Novu (open-source notification infra) |
| Webhooks | Evaluate | n8n (workflow automation, self-hostable) |
| Email delivery | Buy | SES or Postmark — commodity |
| Buy | Gupshup or Twilio | |
| SMS | Buy | Twilio or MessageBird |
| Referral engine | Build | Core growth module — key differentiator |
| Waitlist / Advocacy / Milestones | Build | Core growth modules |
| SDK / Web Components | Build | Developer-facing surface — must own |
| Dashboard | Build | Tenant and admin experience — must own |
Event Schema
Section titled “Event Schema”Every event in GrowthOS follows a canonical JSON schema. This ensures consistent processing across the event bus, database, and PostHog.
{ "event": "referral.completed", "contact_id": "c_8f2a3b1d", "tenant_id": "t_acme_inc", "properties": { "referrer_id": "c_4e7c9a0f", "campaign_id": "camp_launch_2026", "reward_type": "credit", "reward_amount": 20 }, "timestamp": "2026-02-23T14:32:00Z", "source_module": "referrals"}Multi-Tenancy
Section titled “Multi-Tenancy”GrowthOS is multi-tenant by design. Every row in every table includes a tenant_id, and PostgreSQL row-level security (RLS) policies enforce isolation at the database level.
- Every query is automatically scoped by
tenant_id - RLS policies are enforced even if application code has a bug
- Tenant data is partitioned — no cross-tenant leakage by construction
- API keys are scoped to a single tenant
Channel Delivery Abstraction
Section titled “Channel Delivery Abstraction”Modules never talk to delivery channels (email, SMS, WhatsApp, push) directly. Instead, they call an internal comms.send() API that handles provider selection, rate limiting, and delivery tracking.
This means:
- Modules are provider-agnostic — swap SES for Postmark without touching module code
- Rate limiting and retries are centralized, not duplicated per module
- Delivery analytics flow back through the event bus like any other event