Architecture
Build specs in the browser, validate with Zod, generate deterministic output, and share via URL-encoded state.
Overview
Growth OS is a deterministic specification generator for product-led growth teams. Users input product metadata (type, primary object, value action) and configuration choices (activation rules, tracking events), and the system outputs a complete growth specification including KPI trees, activation definitions, tracking plans, and experiment templates.
System Flow
The architecture follows a linear flow from input to shareable output, with validation at each boundary.
Data Model
The core data structure captures everything needed to generate a complete growth specification.
productTypeB2B SaaS vs Devtool. Determines metric naming conventions and default guardrails.
primaryObjectThe core entity users create. Used to generate North Star metric naming.
valueActionThe action that delivers value. Forms the basis of activation event naming.
ttvMinutesTime-to-value in minutes. Informs onboarding experiment design.
activationRulesArray of predefined rule types converted to human-readable rules during generation.
coreEventsEnum-based event selection ensuring consistent event taxonomy across specs.
Generator Design
The generator (generateGrowthSpec) is a pure function: identical inputs always produce identical outputs.
The only non-deterministic element is the timestamp in the footer, which uses the generation date for versioning shared specs.
SSR Strategy
Different pages use different rendering strategies based on their needs.
- Hero/layout server-rendered for fast first paint
- Wizard form as client component with Suspense
- localStorage for draft persistence
- Full SSR: decode → validate → generate on server
- Dynamic OG metadata from decoded spec
- robots: noindex for share URLs
Exports
Three export formats, each with honest tradeoffs.
- • Full spec as structured markdown
- • Tables for tracking plans
- • Copy or download
- • Raw BuilderWizardState
- • Machine-readable
- • Same as URL payload
- • Native window.print()
- • @media print styling
- • Save as PDF in dialog
Validation Strategy
Runtime validation using Zod ensures type safety at system boundaries.
export const GrowthSpecInputSchema = z.object({
productType: ProductTypeSchema.or(z.literal('')),
primaryObject: z.string().min(1).max(50),
valueAction: z.string().min(1).max(50),
ttvMinutes: z.string().regex(/^\d+$/),
activationRules: z.array(ActivationRuleSchema).min(1),
coreEvents: z.array(CoreEventSchema).min(1),
})Testing
Tests run via Vitest (pnpm test).
- pluralize() - singular/plural/custom
- Encoding/decoding round-trips
- Schema validation edge cases
- All static routes return 200
- /s with invalid param shows error
- /s with valid param renders spec
The deterministic generator design means integration tests are effectively unit tests—no external dependencies to mock.
Future Roadmap
Engineering Notes
Key technical decisions that make this codebase recruiter-ready.