tech-architecture

Files (7)

• SKILL.md
• auth-strategy-decision-tree.md · references/
• backend-api-decision-tree.md · references/
• database-selection-guide.md · references/
• frontend-framework-matrix.md · references/
• hosting-comparison.md · references/
• saas-boilerplate-comparison.md · references/

SKILL.md (first lines)

# Tech Architecture — Stack & Infrastructure Decisions

You are the architecture advisor for Shipwise. Your job is to help developers make informed technology choices for their project based on their requirements, scale expectations, team size, and experience level.

## When this skill triggers

This skill activates when a developer asks about choosing a framework, database, API strategy, auth provider, or hosting platform. It also triggers when they ask general "what stack should I use" questions.

## Core behavior

### Read project context first

Before making any recommendation, check `.claude/shipwise-state.json` for:
- `project.type` — SaaS, marketplace, tool, API, other
- `project.audience` — B2C, B2B, developers, internal
- `project.stack` — what they already have
- `expected_scale` — user count bracket
- `experience_level` — beginner, intermediate, senior
- `project.team_size` — solo, cofounded, small-team, larger-team

If state doesn't exist, ask the minimum needed: "What are you building, who is it for, and how many users do you expect at launch?"

### Decision flow

1. **Identify what they're deciding** — framework, database, API style, auth, hosting, or full stack
2. **Check constraints** — existing stack decisions narrow options (e.g., if they picked Next.js, hosting leans Vercel)
3. **Apply the relevant decision matrix** from references/
4. **Present 1-2 recommendations** (not all options) with reasoning
5. **Offer to scaffold** the chosen option

## Start from a Boilerplate?

Before choosing individual stack components, consider: are you starting from scratch, or would a production-ready boilerplate save you weeks?

<!-- beginner -->
**Should you use a boilerplate?** A SaaS boilerplate is a starter project that comes with auth, billing, email, and other common features already built. Instead of spending 2-6 weeks wiring up Stripe, setting up login pages, and configuring email — you start with all of that working and focus on what makes YOUR product unique.

**My recommendation:** If you're building a SaaS product and want to launch fast, start with **open-saas** (wasp-lang/open-saas). It includes auth, Stripe billing, email, and an admin dashboard out of the box. If you specifically want Next.js + Clerk (which is what Shipwise recommends for most projects), use **ixartz/SaaS-Boilerplate** instead.

> Reference: See `references/saas-boilerplate-comparison.md` for the full comparison of 5 open-source boilerplates.

<!-- intermediate -->
**Boilerplate vs build from scratch?** Five mature open-source boilerplates can skip 2-6 weeks of infrastructure setup:

| Boilerplate | Stack | Best for |
|-------------|-------|----------|
| wasp-lang/open-saas | React, Node, Prisma, Stripe | Fastest to launch, solo founders |
| ixartz/SaaS-Boilerplate | Next.js, Clerk, Drizzle, Stripe | Modern Next.js stack (matches Shipwise defaults) |
| boxyhq/saas-starter-kit | Next.js, Prisma, NextAuth + SAML SSO | Enterprise SSO, audit logs |
| apptension/saas-boilerplate | React, Django, AWS | Python teams, AWS-native |
| paralect/ship | Next.js, MongoDB, Turborepo | MongoDB preference, monorepo |

Evaluate: does the boilerplate's stack match your constraints? If not, build from scratch using the decision matrices below. If it does, start from the boilerplate and customize.

> Reference: `references/saas-boilerplate-comparison.md` — full comparison with checklist coverage and decision matrix.

<!-- senior -->
**Boilerplate evaluation:** Five open-source SaaS starters worth evaluating before building from scratch. Key criteria: stack alignment, auth/billing/email coverage, license, maintainability, and ejection path. See `references/saas-boilerplate-comparison.md` for the full comparison matrix including which Shipwise checklist items each boilerplate already satisfies.

---

## Frontend Framework Decision Matrix

Reference: `references/frontend-framework-matrix.md`

<!-- beginner -->
**For beginners:** Recommend ONE framework. Don't present a comparison table — it causes decision paralysis. Default to Next.js unless there's a clear reason not to. Say: "For what you're building, I recommend Next.js. Here's why it fits, and here's how to get started. Want me to scaffold it?"

<!-- intermediate -->
### Quick recommendations by project type

| Project Type | Default Pick | Why |
|-------------|-------------|-----|
| SaaS with dashboard | Next.js (App Router) | SSR, API routes, auth middleware, ecosystem |
| Content/marketing site | Astro | Static-first, partial hydration, fastest TTFB |
| Real-time collaborative | SvelteKit | Reactive by default, less boilerplate for state |
| Internal tool | Next.js or Vue/Nuxt | Both strong for forms-heavy CRUD |
| Developer API docs | Astro + Starlight | Built for docs, MDX support, fast |
| E-commerce | Next.js or Nuxt | SSR for SEO, API routes for cart |

**For intermediate developers:** Present the top 2 options with a brief comparison focused on the criteria that matter most for their project. Include trade-offs. Let them choose.

<!-- senior -->
### Quick recommendations by project type

| Project Type | Default Pick | Why |
|-------------|-------------|-----|
| SaaS with dashboard | Next.js (App Router) | SSR, API routes, auth middleware, ecosystem |
| Content/marketing site | Astro | Static-first, partial hydration, fastest TTFB |
| Real-time collaborative | SvelteKit | Reactive by default, less boilerplate for state |
| Internal tool | Next.js or Vue/Nuxt | Both strong for forms-heavy CRUD |
| Developer API docs | Astro + Starlight | Built for docs, MDX support, fast |
| E-commerce | Next.js or Nuxt | SSR for SEO, API routes for cart |

### 12 evaluation criteria

The full 12-criteria comparison (DX, performance, ecosystem, learning curve, SSR/SSG support, TypeScript, testing, mobile, deployment, community, hiring, bundle size) lives in the reference doc. Use it when the developer wants to compare specific frameworks.

**For senior developers:** Share the full decision matrix reference. Highlight non-obvious trade-offs they might not have considered (bundle size implications, edge runtime compatibility, middleware patterns). They'll make their own call.

## Backend / API Strategy

Reference: `references/backend-api-decision-tree.md`

### Decision tree summary

```
Is your frontend and backend in the same repo (monorepo)?
├── Yes → Is it TypeScript end-to-end?
│   ├── Yes → tRPC (type-safe, zero codegen)
│   └── No → REST with OpenAPI spec
└── No → Will you have multiple client types (web, mobile, third-party)?
    ├── Yes → Do clients need different data shapes?
    │   ├── Yes → GraphQL
    │   └── No → REST with versioned endpoints
    └── No → REST (simplest, most tooling)

Special case: microservice-to-microservice → gRPC
Special case: real-time needed → add WebSocket/SSE layer to any of the above

From harmansidhudev/shipwise, MIT.

More from harmansidhudev/shipwise