Siza

The open full-stack AI workspace — generate, integrate, ship.

Every AI code tool generates beautiful frontends. Then you spend days wiring auth, database, APIs, and deployment. Siza owns the full-stack integration layer — from idea to production, zero lock-in.

Live: siza.forgespace.co

Dev: dev.forgespace.co

Why Siza

What we are	What we're NOT
Open-source workspace you can self-host	Locked-in SaaS like v0.dev
Full-stack (UI + backend + deploy)	Frontend-only generator
MCP-native (composable AI tools)	Monolithic AI black box
Privacy-first (BYOK, zero telemetry)	Data-harvesting freemium
Generous free tier by default	Free trial with paywall

Features

• AI-Powered Generation — Natural language or screenshot to production-ready UI components
• MCP-Native — Generation, governance, migration, and branding capabilities composed via MCP
• Privacy-First BYOK — Bring Your Own Key with client-side AES-256 encryption
• Generous Free Tier — Cloudflare Workers + Supabase + Gemini free tiers give you a generous starting point at $0/month
• Self-Hostable — Run everything locally with Docker, MIT licensed
• Multi-LLM — Swap between Gemini, Claude, GPT without code changes
• Production Ready — Monaco editor, live preview, Stripe billing, feature flags
• IDP Governance — Software catalog, golden path templates, post-gen scorecard, dependency graph, API docs viewer, CI/CD visibility, governance plugins
• Theme Generator — Deterministic preset + seed-color theme generation in Generate flow

UI Migration Status (March 2026)

• Design tokens migrated from --siza-* to --forge-* (Phase 2). App theming now uses @forgespace/brand-guide forge-tokens; legacy aliases (--surface-0, --brand, etc.) point to --forge-* for backward compatibility
• Dashboard shell chrome aligned to design-system structure (56px top bar, breadcrumbs, command search, notifications indicator, token-consistent backgrounds/borders)
• Auth shell rebuilt to centered 440px card + radial glow/pattern and updated sign-in/sign-up/forgot/reset form controls to design-system styling
• Landing page hero/nav/footer moved closer to flagship design-system hierarchy (public beta badge, production-grade hero line, docs secondary CTA, product/resources/company/legal footer columns)
• Projects surface now includes design-system-inspired grid/list toggle and upgraded card presentation with framework badges and progress bars
• Unified dashboard route metadata for Sidebar, MobileNav, and breadcrumb/page title resolution
• Added migration primitives (AuthCardShell, MarketingSection, DashboardSection) and shared style utilities in globals.css
• Migrated mapped route visuals across landing/about/auth/dashboard surfaces while preserving behavior contracts (middleware, OAuth callback, query-param pages)
• Redesigned gap routes (reset-password, legal pages, maintenance, billing success) into the current Siza visual language
• Added role-aware dashboard navigation and a new Admin page for feature flag management
• Landing page performance pass: removed force-dynamic homepage personalization, switched to static public CTAs, and replaced Motion-heavy above-the-fold effects with server-rendered sections and CSS transitions
• Lighthouse accessibility pass: raised subtle text contrast token and aligned footer/code-surface secondary text to contrast-safe values
• Landing nav runtime pass: replaced client-side Sheet/scroll nav logic with server-rendered disclosure navigation + in-page anchors, and disabled homepage internal-link prefetch to avoid eager loading non-critical route bundles

Quick Start

git clone https://github.com/Forge-Space/siza.git
cd siza
npm install
supabase start
supabase db push
npm run dev

Open localhost:3000. Supabase Studio at localhost:54323.

Environment Setup

Create apps/web/.env.local:

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-local-service-role-key
NEXT_PUBLIC_GA_TRACKING_ID=G-XXXXXXXXXX
GEMINI_API_KEY=your-gemini-key
# Optional backup capacity for quota/rate-limit fallback
ANTHROPIC_API_KEY=your-anthropic-key
DEFAULT_GENERATION_PROVIDER=google
NEXT_PUBLIC_ENABLE_BYOK=true
NEXT_PUBLIC_ENABLE_GEMINI_FALLBACK=true
NEXT_PUBLIC_E2E_DISABLE_TOUR=false
SIZA_AGENT_LOCAL_FALLBACK=false

Generation reliability behavior

• Siza defaults to siza -> google routing for shared free-tier generation
• On provider quota/rate-limit, the server falls back to Anthropic when ANTHROPIC_API_KEY is configured
• If enabled (SIZA_AGENT_LOCAL_FALLBACK=true), provider failures without chunks can fallback to local @forgespace/siza-gen
• Fallback never reuses the primary provider BYOK key for backup provider calls
• When no backup capacity is configured, users get explicit capacity guidance with BYOK next steps

Lead attribution and signup events

• First-touch attribution is captured from URL params and stored in browser local storage: utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, gbraid, wbraid, landing_path, first_seen_at
• Signup now sends marketing_attribution in Supabase auth metadata
• GA4 lead events emitted during signup: lead_signup_started, lead_signup_success, lead_signup_oauth_start, lead_signup_error
• Unit coverage validates signup attribution metadata and lead event emission in SignUpPage auth tests
• Public auth routes now expose a page-level h1 inside a proper main landmark, and the gallery empty state always offers onward actions (/templates plus /signup or /generate depending on session state)

MCP-first routing policy

• ENABLE_MCP_GATEWAY=true with MCP_GATEWAY_URL configured keeps generation on the MCP path
• ENABLE_MCP_DIRECT_PROVIDER_FALLBACK is disabled by default to avoid silent direct-provider failover in MCP mode
• If you need emergency fallback behavior, set NEXT_PUBLIC_ENABLE_MCP_DIRECT_PROVIDER_FALLBACK=true

Validation and quality metrics

GET /api/metrics reports live telemetry with strict bearer auth (METRICS_API_KEY):

• Users (total, last7d, last30d, active)
• Generations (total, last24h, last7d, successRate)
• Projects (total)
• Quality (revisionRate, satisfactionRate, mcpCoverage) with optional windowDays=7|30|90 (default 30)

Admin UI (/admin) now includes a live Product Telemetry section backed by GET /api/admin/metrics (admin session required).

Security Spoke telemetry is also available in Admin (/admin) with:

• GET /api/admin/security (admin-only, supports windowDays=7|30|90)
• live summary, risk/severity distribution, top rules, and recent high-risk generations
• per-generation persistence from MCP stream quality events (security_spoke)

Required runtime env:

METRICS_API_KEY=replace-with-strong-random-token

Grant admin access locally

Create/sign in the target user first, then run:

npm run admin:grant -- lucas.diassantana@gmail.com

This updates public.profiles.role to admin for that email.

Core-flow validation snapshots

Siza now tracks roadmap gate progress in Admin (/admin) with:

• live gate metrics (GET /api/admin/validation, admin-only)
• activation funnel telemetry (windowDays=7|30|90) with onboarding/project/generation conversion and top drop-off reasons
• additive activation bottleneck block in GET /api/admin/validation with:
  • onboardedWithoutProject
  • projectWithoutCompletedGeneration
  • deterministic nextBestAction (CREATE_PROJECT or COMPLETE_GENERATION)
• daily trend snapshots (POST /api/internal/validation/snapshot, bearer token protected)
• internal gate status report (GET /api/internal/validation/report, bearer token protected)

Activation UX is now surfaced directly in product:

• Onboarding includes qualification nudges and deterministic telemetry events for step views/completions/skips/CTA clicks
• Onboarding skip/complete routes now push users toward the next qualifying action (project creation or project-aware generation route)
• Onboarding done-step primary CTA now supports one-click starter project creation and routes directly to a project-aware Generate flow
• Dashboard shows a persistent Core Flow Progress checklist with a single primary next-action CTA until the user is qualified
• Dashboard now includes a guided one-click starter-project prompt for the onboarding-complete/no-project cohort with explicit confirm + "Not now" actions
• Guided starter-project creation routes directly to project-aware Generate on success, and falls back to manual project creation routing if creation fails
• Dashboard primary generation surfaces now keep this cohort on project-first routing (header, empty-state, and quick-action generate entry) while preserving project-aware Generate links for users who already have a project
• Dashboard no-project conversion CTAs now run one-click starter-project creation across header primary, empty-state primary, quick-action generate, and checklist next-step actions, with deterministic entry=<cta>&step=project routing params
• Onboarding no-project skip/done exits now route to dashboard conversion intent (/dashboard?...&intent=create_project) instead of sending users directly to manual project creation
• Activation lifecycle telemetry is now emitted for starter conversion flows: activation_starter_project_confirmed, activation_starter_project_created, activation_starter_project_fallback, and activation_route_to_generate

Required runtime env:

METRICS_SNAPSHOT_TOKEN=replace-with-strong-random-token

GitHub automation:

• Workflow: .github/workflows/core-flow-validation-snapshot.yml
• Workflow: .github/workflows/core-flow-validation-report.yml
• Report schedule: daily at 03:20 UTC and weekly gate rollup at 03:25 UTC (Mondays)
• Repository variable: SIZA_BASE_URL (for example https://siza.forgespace.co)
• Repository secret: METRICS_SNAPSHOT_TOKEN

Manual snapshot trigger:

curl -X POST "$SIZA_BASE_URL/api/internal/validation/snapshot" \
  -H "Authorization: Bearer $METRICS_SNAPSHOT_TOKEN"

Manual report trigger:

curl "$SIZA_BASE_URL/api/internal/validation/report" \
  -H "Authorization: Bearer $METRICS_SNAPSHOT_TOKEN"

Architecture

forge-patterns (shared standards)
    |
    v
mcp-gateway (AI tool routing) --> siza-mcp (UI/backend generation tools)
    |                              branding-mcp (brand identity tools)
    v
siza (this repo)
├── apps/web      — Next.js 16 frontend (Cloudflare Workers)
├── apps/desktop  — Electron desktop app (local Ollama + MCP)
└── apps/api      — Backend API service

Stack

Layer	Technology
Frontend	Next.js 16 (App Router), React 19, TypeScript 5.7
UI	Tailwind CSS, shadcn/ui, Radix, Monaco Editor
State	Zustand, TanStack Query
Auth/DB	Supabase (PostgreSQL 15, Auth, Realtime, Storage)
AI	Gemini 2.0 Flash, Anthropic SDK, MCP SDK
Email	Resend + react-email templates
Billing	Stripe (Checkout, Portal, Webhooks)
Deploy	Cloudflare Workers via OpenNext
Monorepo	Turborepo

Project Structure

siza/
├── apps/
│   ├── web/                  # Next.js 16 frontend
│   │   ├── src/app/          # App Router pages & API routes
│   │   ├── src/components/   # shadcn/ui components
│   │   ├── src/lib/          # Auth, Stripe, usage, features
│   │   └── e2e/              # Playwright E2E tests
│   ├── docs/                 # Fumadocs documentation site
│   ├── desktop/              # Electron desktop app
│   └── api/                  # Backend API service
├── packages/
│   ├── ui/                   # @siza/ui shared component library
│   └── eslint-config/        # Shared ESLint config
├── supabase/                 # Migrations (10), seed data
└── turbo.json                # Turborepo config

Development

npm run dev             # Start dev server (localhost:3000)
npm run build           # Build for production
npm run lint            # ESLint
npm test                # Unit tests (Jest)
npm run test:e2e        # E2E tests (Playwright)
npm run test:e2e:prod   # Production Chromium audit (artifacts + issues map)
npm run type-check      # TypeScript
npm run sync:golden-paths # Sync official Golden Paths seeds
npm run sync:skills     # Sync official skills from skills/*/SKILL.md

Lead-readiness and ads prepublish checks

cd apps/web
npm run test:e2e:lead:preflight
npm run test:e2e:lead:chromium
npm run ads:google:prepublish
npm run test:e2e:prod

• test:e2e:lead:preflight validates generation backend readiness (MCP gateway, provider key, or local fallback)
• test:e2e:lead:chromium runs Chromium smoke for lead-critical flows
• ads:google:prepublish runs preflight + marketplace smoke and prints manual GA4/Ads checks
• test:e2e:prod runs production audit packs (public + auth by default) and writes artifacts to apps/web/test-results/production/<run-id> plus issues-map.json from real failing tests and runtime API probes
• Runtime probes in test:e2e:prod assert unauthenticated generation endpoints return 401 (/api/generations, /api/generations/history, /api/generations/[id])
• Lead-readiness checkout smoke in production audit accepts 403 Billing is not enabled when billing is disabled and expects 200 + url when billing is enabled
• Campaign assets for siza_br_en_leadtest_v1 are in apps/web/marketing/google-ads/siza_br_en_leadtest_v1
  • campaign-config.json
  • keywords.csv
  • negative-keywords.csv
  • rsa.json
  • day1-ops.md
• Auth/onboarding/stripe lead smoke now uses shared Supabase admin helpers and deterministic webhook payloads for CI stability
• Lead-readiness production smoke now dismisses the guided tour overlay before post-generation code-tab assertions to avoid pointer interception during disposable-user runs
• Catalog E2E creation now supports both direct detail redirects and list-first redirects by resolving created entry IDs via API lookup

Playwright MCP Wrapper (Codex Runtime)

Siza ships .mcp.json with a wrapper-first playwright MCP server:

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": ["scripts/playwright-mcp-wrapper.mjs", "--headless"]
    }
  }
}

If your global Codex MCP registry still points playwright to direct npx @playwright/mcp and calls fail with Transport closed, re-register with the local wrapper that bridges Content-Length and newline JSON-RPC transport styles.

codex mcp remove playwright
codex mcp add playwright -- \
  node /absolute/path/to/siza/scripts/playwright-mcp-wrapper.mjs --headless

Then restart Codex to reload MCP server configuration.

Local smoke check:

npm run mcp:playwright:wrapper -- --help

Governance Asset Sync

Siza keeps official governance assets (Golden Paths and Skills) syncable from repository sources.

npm run sync:golden-paths
npm run sync:skills

Required environment variables:

• SUPABASE_SERVICE_ROLE_KEY
• SUPABASE_URL or NEXT_PUBLIC_SUPABASE_URL

Generation E2E modes

• Default CI-safe suite uses mocked /api/generate SSE for deterministic generation/preview assertions
• Optional live-provider smoke test is gated behind E2E_LIVE_PROVIDER=true
• Live smoke uses BYOK provider selection (GEMINI_API_KEY or ANTHROPIC_API_KEY)
• If Gemini preflight returns quota/rate-limit (HTTP 429), smoke auto-switches to Anthropic when available
• If Gemini is quota-limited and Anthropic key is unavailable, smoke skips with an explicit reason
• Live smoke prerequisites: SUPABASE_SERVICE_ROLE_KEY, NEXT_PUBLIC_SUPABASE_URL, and at least one provider key (GEMINI_API_KEY or ANTHROPIC_API_KEY)

CI Security Hygiene

• GitHub Actions and reusable workflow references in .github/workflows/ are pinned to full commit SHAs.
• Placeholder DNS/IP examples in UI/test fixtures avoid real private-network literals.
• Regex-based content extraction paths use bounded or parser-based logic to reduce ReDoS risk.
• Desktop dependency chain is audited explicitly in CI (npm audit --workspace=apps/desktop --audit-level=high).
• CI also prints desktop tar resolution (npm ls tar --workspace=apps/desktop) to make transitive remediation visible in logs.
• High severity dependency advisories are fixed in the active cycle; medium/low advisories are tracked in follow-up issues when non-breaking fixes are not available. Project operation notes for AI agents and contributors are in AGENTS.md.

Live Ecosystem Sync (Marketing)

Marketing pages consume a server-only GitHub metadata sync for the Forge Space ecosystem (repo count, latest release tag, recent activity).

• Sync source: GitHub REST API (Forge-Space org)
• Cache strategy: revalidate: 21600 (6 hours)
• Resilience: static fallback snapshot if GitHub is unavailable/rate-limited

Optional authentication (for higher GitHub API limits):

FORGE_SPACE_GITHUB_TOKEN=ghp_...
# fallback when FORGE_SPACE_GITHUB_TOKEN is unset
GITHUB_TOKEN=ghp_...

SEO and Indexability (Marketing)

Siza uses an explicit SEO contract for marketing and legal pages.

Indexable routes:

• /
• /about
• /roadmap
• /pricing
• /docs
• /gallery
• /legal/privacy
• /legal/terms

Technical behavior:

• Route-level metadata map with canonical, title, description, keywords, Open Graph, and Twitter fields
• robots.txt and sitemap.xml are generated from the marketing route allowlist
• /landing is excluded from indexing (redirect target only)
• Non-marketing surfaces are noindex/disallowed (/api/*, dashboard/app/auth/onboarding/utility paths)
• Marketing pages are static/ISR-friendly and do not depend on server auth state
• Structured data:
  • Homepage: Organization + WebSite + SoftwareApplication
  • Marketing/legal pages: WebPage JSON-LD

Pricing

Free for individuals, paid for scale and convenience.

Tier	Price	Generations	Projects
Free	$0 forever	10/month (BYOK unlimited)	2
Pro	$19/month	500/month	Unlimited
Team	$49/month (5 seats)	2,500/month	Unlimited
Enterprise	Custom	Unlimited	Unlimited

The Forge Space Ecosystem

Siza is part of Forge Space — 11 product repositories that ship as one open platform:

Repo	Purpose
siza	AI workspace (this repo)
core	Shared standards and governance contracts
mcp-gateway	MCP routing and reliability hub
ui-mcp	MCP protocol adapter for generation/migration
siza-gen	AI generation engine and quality context
forge-ai-init	Governance CLI and migration analysis
forge-ai-action	CI quality gates for pull requests
branding-mcp	Brand identity MCP toolkit
brand-guide	Design tokens and identity source
forgespace-web	Forge Space marketing website
siza-desktop	Local-first desktop companion app

Deployment

Cloudflare Workers (Production)

Automated via GitHub Actions on push to main (production) or dev (preview):

1. Set GitHub Secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, NEXT_PUBLIC_BASE_URL
2. Set GitHub Variable: CLOUDFLARE_DEPLOY_ENABLED=true
3. Deployment runs automatically via deploy-web.yml

Free Tier Architecture

Service	Free Tier
Cloudflare Workers	Unlimited bandwidth
Supabase	50K MAU, 500MB DB, 1GB storage
Gemini 2.0 Flash	60 RPM
GitHub Actions	2,000 min/month

Documentation

Full documentation is available in the apps/docs/ directory, built with Fumadocs:

npm run dev --workspace=apps/docs  # localhost:3001

Covers: quick start, self-hosting, configuration, MCP integration, API reference, and architecture.

Community

• GitHub Discussions — questions, ideas, show & tell
• Issue Templates — bug reports, feature requests, security reports
• Contributing Guide — how to contribute code and docs

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

1. Fork the repo
2. Create a feature branch from main
3. Make changes, run npm run lint && npm test && npm run build
4. Open a PR against main

License

MIT — see LICENSE.

---

Part of the Forge Space ecosystem.