Vision

1. Purpose

Why

Skip infrastructure setup. Focus directly on business features.

"The house foundations. Build whatever you want on top."

For Whom

• Solo developers
• Small teams (2-3 devs)
• Early-stage startups

Target Products

• B2B: Internal tools, dashboards, admin panels
• B2C: Basic user-facing apps
• Long-term focus: Built for scalability, not throwaway MVPs

Non-Goals

• Not a CMS
• Not an e-commerce platform
• Not for mobile native apps
• Not a marketplace builder

Success Criteria

"When I build my first business feature, it just works."

• Auth, multi-tenant: ready out of the box; billing: architecture-ready (Phase 2)
• Developer experience: smooth, no friction
• Code patterns: clear, consistent, scalable

Measurable:

• Time to first feature: Minimal time to add a business feature
• Zero config: Clone → dev in less than 5 minutes
• Production-ready: Deployable to prod without modifications

2. Principles

North Stars

1. Simplicity first - Fewer features but they work perfectly
2. Scalability - Built to grow, not to throw away
3. Convention over configuration - Strong opinions, fewer decisions to make

Trade-offs

Non-Negotiables

• TypeScript strict mode everywhere
• TDD: tests written before code
• All quality gates must pass before merge
• Documentation maintained like code

3. AI Team & Skills

Two Categories of AI Agents

The boilerplate distinguishes between two types of AI agents:

Development Agents - Assist in building the SaaS

Runtime Agents - Interact with the deployed SaaS

Planned — Runtime agents are not yet implemented. This describes a future capability.

CLI for AI Interaction

A CLI generated from OpenAPI specs enables AI agents to interact with the SaaS API:

• Universal access: Any AI capable of running bash can use it
• Human-friendly: Developers can also use it for testing and debugging
• Auto-generated: Stays in sync with API changes

Skills Organization

Planned — The Marketplace and Git-based skill sources are not yet implemented. Only built-in skills are currently available.

Orchestration

• Workflow-driven: Predefined workflows chain agents
• Event-driven: Agents react to events (hooks, PR, etc.)
• Autonomy: Autonomous agents, human review afterwards

4. Developer Experience

Code Methodology

• Strict TDD: Tests written before code, always
• Functional patterns where appropriate
• Named exports over default exports
• No circular dependencies

Quality Gates (All Required for Merge)

• Lint clean (Biome)
• TypeScript error-free
• All tests pass
• Minimum coverage threshold met
• Review approved (human or AI)

Documentation Strategy

Testing Philosophy

• Unit/Integration: Vitest
• E2E: Playwright
• Coverage: Minimum threshold enforced
• TDD: Test first, implementation second

5. Architecture

Monorepo Structure

roxabi_boilerplate/
├── .env                    # Global environment variables
├── apps/
│   ├── web/               # Frontend + Documentation (TanStack Start + Fumadocs)
│   └── api/               # Backend (NestJS + Fastify)
├── packages/               # Shared code
│   ├── ui/                # Shared UI components
│   ├── config/            # Shared configurations
│   ├── types/             # Shared TypeScript types
│   ├── email/             # Email templates
│   ├── vitest-config/     # Shared Vitest configuration
│   └── playwright-config/ # Shared Playwright configuration
├── docs/                   # Documentation content (MDX files)
└── .claude/                # Claude Code configuration

Multi-Tenant Model

Strategy: Row-Level Security (RLS)

• Single database
• Isolation by tenant_id + PostgreSQL RLS
• Performant, simple to maintain

API Design

• Style: REST
• Documentation: OpenAPI/Swagger auto-generated
• Contracts: Shared types via @repo/types
• CLI: Auto-generated from OpenAPI spec for human and AI interaction

Data Flow

6. Workflows

Branching Strategy

Staging-based workflow (Git Flow lite)

• main = production — merges trigger auto-deploy
• staging = integration branch — all feature/fix branches branch from here and PR back
• hotfix/* branches may target main directly for urgent production fixes
• PR required for all merges

Development Workflow

Automations (Hooks)

Deployment Strategy

Continuous Deployment via Vercel

• Merge to main = auto-deploy both apps on Vercel
• Web (TanStack Start) → Vercel (SSR, edge caching, Fluid compute)
• API (NestJS) → Vercel (zero-config NestJS, Fluid compute)
• Docker configs included for self-hosted/VPS alternative

Hotfix Process

• Create hotfix/* branch from main, open PR targeting main
• Rollback via Vercel dashboard (promote previous deployment)

7. Roadmap

Phase 1: MVP

Scope

• Auth + Users (Better Auth)
• Multi-tenant (RLS)
• RBAC (roles and permissions)
• i18n (Paraglide JS — compile-time, type-safe)
• Design system (Shadcn/UI + CVA + design tokens)
• Security hardening (CORS, CSP, input sanitization)
• Agent Teams (9-agent AI development team)
• Admin panel (backlog — #25)
• Audit logs (backlog)
• Notifications (backlog)

Success Criteria

• Clone → dev in less than 5 min
• First business feature added quickly
• Deployable to production without modifications

Phase 2+: Backlog

To be prioritized later:

• CLI generated from OpenAPI (AI-ready)
• Billing (Stripe/Paddle/Lemon Squeezy via abstraction)
• Analytics dashboard
• Webhooks
• Public API
• Additional OAuth providers
• Plugins/extensions system
• Themes
• Marketplace

8. Technical Decisions

Decided

Abstracted (Implementation at Deploy)