
Refract
Every SaaS pivots. Most codebases don't survive it.
Product Description
Refract is a production-grade TypeScript SaaS boilerplate for teams that expect to pivot: pricing, plans, and integrations should be configuration—not a rewrite.
WHAT YOU GET
- Billing — Stripe: dynamic plans/tiers, metered usage, proration, multi-currency, grace periods, checkout/upgrade/downgrade/cancel, billing controls, custom checkout UX. Idempotent webhooks and retries for production failure modes.
- Auth & B2B — Multi-tenancy, scoped RBAC, password + OAuth, sessions, users, invites/revokes.
- Infrastructure — Swap queue (SQS, BullMQ), mail (Brevo, SendGrid), cache, analytics adapters. Background jobs and email included.
- Apps — GraphQL + codegen, Apollo server/client, React + MUI, TypeScript end-to-end.
- Marketing + authenticated app in one monorepo.
- Stack — PostgreSQL (Sequelize), Redis, Express, Apollo Server.
- Observability — Structured logging, metrics (StatsD-oriented), analytics hooks.
- Tests — 80%+ on billing and auth.
- DX — Docker Compose, Makefile, CI (lint/build/test/codegen). Dev proxy: one origin for marketing, portal, API (OAuth/CORS like prod). Stripe CLI in Compose. Railway documented.
- Docs & AI — In-repo onboarding and config. Cursor rules for consistent changes across backend, portal, tooling.
- Principles — Composable core; vendor code behind swappable contracts so mail/queue/provider changes are adapter work.
- Security — Validate at boundaries; ORM for DB; RBAC as product. Prefer bounded telemetry tags.
Who — Indie founders / small B2B teams; past-MVP teams; builders avoiding full rewrites when vendors change.
Why — Explicit boundaries + functional patterns. Full stack in Docker for repeatable onboarding.
Not a demo — Built for support load, billing edge cases, roles, integrations you have not chosen.
The pivot is a config change, not a rewrite.
Tech — React 19, Vite, MUI, Redux Toolkit, Apollo Client, React Router, RHF. Node, Express, Apollo Server, Sequelize, Postgres, Redis, Passport/JWT. Stripe; SQS/BullMQ; Brevo/SendGrid.
Features
- Business & Revenue Infrastructure
- Engineering & Delivery Speed
- Ops & Reliability
Use Cases
- 🚀 The High-Stakes B2B Startup
- The Problem: You need to ship an MVP that looks like an Enterprise product (Orgs, Roles, Permissions) but your pricing model is still an experiment.
- The Refract Edge: Launch with a robust B2B foundation on day one. If you decide to pivot from a $50/mo subscription to a usage-based credit model or a $2,000 one-off license, you swap a configuration adapter rather than rewriting your core billing logic.
- 🛠️ The "Modern" Agency & Studio
- The Problem: Delivering high-quality custom SaaS for clients is slow because you’re constantly re-wiring Auth, Stripe, and Webhooks for every new project.
- The Refract Edge: Use Refract as your "Gold Image." Its modular boundaries allow you to swap mail providers (Postmark vs. Resend) or databases per client while keeping a consistent, type-safe codebase that your team actually understands.
- 🤖 The AI-Native Product
- The Problem: You’re building a wrapper or an agent-led tool where the code needs to be extremely organized so that AI coding assistants (like Cursor) don't hallucinate or break the logic.
- The Refract Edge: Symmetric Legibility. Our "Direct-Map" directory structure provides a clear mental model for both humans and LLMs. The strict functional core ensures that AI-generated refactors stay within their lanes and don't leak into your infrastructure.
- 📈 The Hybrid Commerce Platform
- The Problem: You want to sell a "Pro" subscription but also offer one-off "Power Packs," digital downloads, or top-up credits.
- The Refract Edge: Refract handles the complexity of hybrid revenue. It’s a complete commerce engine that manages recurring MRR and one-time transactional sales within the same unified organizational context.



