Technical Deep Dive
An honest look at how Growth OS works today: architecture decisions, tradeoffs acknowledged, and future possibilities clearly labeled.
Overview
Growth OS is a deterministic specification generator for product-led growth teams. Users configure their product metadata (type, primary object, value action) and the system outputs complete growth specifications including KPI trees, activation definitions, and tracking plans.
The entire application runs client-side with no backend—all state is encoded into shareable URLs using lz-string compression. Share pages are server-rendered for proper OG meta tags and instant first paint.
This architecture was chosen deliberately to minimize operational complexity while maximizing portability: specs can be bookmarked, shared via any medium, and work forever without server dependencies.
System Flow
The architecture follows a linear, unidirectional flow from user input to shareable output:
generateGrowthSpec() is a pure function: identical inputs always produce identical outputs. No randomness, no external dependencies.JSON.stringify → compressToEncodedURIComponent creates a URL-safe string. Typical specs compress to ~1-2KB./s?d=... pages are server-rendered: decode → validate → generate happens on the server for proper OG meta tags and instant first paint.Key Decisions
Technical choices that define the architecture, with rationale for each.
Deterministic Generator
The generateGrowthSpec() function is pure: same inputs always produce identical outputs. No Math.random(), no timestamps in output (only footer versioning), no external API calls.
Zod Schema Validation
Runtime validation at every boundary: form steps, URL decode, generator input. TypeScript types are inferred from schemas, ensuring compile-time and runtime safety are in sync.
No Backend by Default
The entire application runs without a database, authentication system, or API server. All state lives in the URL or localStorage.
SSR for Share Pages
While the builder is client-heavy, share URLs (/s?d=...) are fully server-rendered. This hybrid approach optimizes for different user journeys.
Tradeoffs
Every architecture has tradeoffs. Here's what we gave up and why we think it's worth it.
Complex specs produce URLs of ~1-2KB. While most browsers support 8KB+ URLs, some tools (Slack, email clients) may truncate long URLs.
Without a database, users can't save specs to an account. They must bookmark URLs or export to files. There's no revision history or team sharing.
Share page SSR requires the generator to run on the server, adding complexity to the client/server boundary. Server errors must be handled gracefully.
We can't track which specs are popular or how users interact with them. This is a deliberate privacy tradeoff.
Future Options
These features are not currently implemented. They represent possible evolution paths, clearly labeled as future possibilities.
Optional: User Accounts & Storage
Adding authenticated accounts would enable persistent spec storage, revision history, and team collaboration features.
- New database (Supabase/Postgres) to store user specs
- Auth provider integration (OAuth, magic links)
- Short URLs replacing lz-string encoded URLs
- Revision history with diff view
- Team workspaces with role-based access
Optional: Analytics Platform Integration
Direct export to Amplitude, Mixpanel, or Segment tracking plan formats.
- New export targets in the generator
- Platform-specific schema mappings
- Optional API integration for direct push
Optional: Community Templates
A curated library of community-contributed spec templates for different industries and use cases.
- Template submission and review workflow
- Searchable template gallery
- Template versioning and attribution