@polymorphism-tech/morph-spec 3.0.1 → 3.1.0

package/stacks/nextjs-supabase/.morph/examples/saas-nextjs-supabase/decisions.md

@@ -0,0 +1,121 @@
+# Multi-Tenant SaaS - Architectural Decision Records
+
+## ADR-001: RLS-Based Tenant Isolation vs Schema-Per-Tenant
+
+**Status**: Accepted
+
+**Context**: Choose a multi-tenancy strategy for data isolation. The two main approaches are (a) shared database with Row Level Security filtering by tenant_id, and (b) separate PostgreSQL schema per tenant.
+
+**Decision**: RLS-based tenant isolation with a single shared schema.
+
+**Rationale**:
+- Supabase natively supports RLS with built-in functions like `auth.uid()` and custom JWT claims
+- Single schema simplifies migrations (one migration applies to all tenants)
+- More cost-effective: one Supabase project serves all tenants
+- Scales well to thousands of small-to-medium tenants
+- Custom JWT claim `app_metadata.tenant_id` provides tenant context automatically
+
+**Alternatives Considered**:
+- Schema-per-tenant: Better isolation but Supabase does not natively manage multiple schemas per project. Migration management becomes complex. Operational overhead grows linearly with tenant count.
+- Database-per-tenant: Maximum isolation but requires separate Supabase projects. Cost-prohibitive ($25/tenant/month on Pro).
+
+**Consequences**:
+- All queries must include tenant_id (enforced by RLS, not application code)
+- Careful attention needed for admin/service-role queries that bypass RLS
+- Bulk data export for a single tenant requires explicit filtering
+- Index strategy must account for tenant_id prefix on all key queries
+
+---
+
+## ADR-002: Stripe for Subscription Billing
+
+**Status**: Accepted
+
+**Context**: Choose a billing provider for SaaS subscription management.
+
+**Decision**: Stripe Billing with Checkout Sessions and Customer Portal.
+
+**Rationale**:
+- Industry standard for SaaS billing with mature subscription lifecycle management
+- Stripe Checkout handles PCI compliance (no card data on our servers)
+- Customer Portal lets users self-manage subscriptions, reducing support burden
+- Webhook-driven architecture integrates cleanly with our event-based approach
+- Extensive test mode for development without real charges
+- Global reach with support for 135+ currencies
+
+**Alternatives Considered**:
+- Paddle: Simpler tax handling (Merchant of Record) but less customization and higher fees
+- LemonSqueezy: Good for indie hackers but less mature API and limited webhook events
+- Custom implementation: Too complex for MVP, PCI compliance burden
+
+**Consequences**:
+- Stripe fees: 2.9% + $0.30 per transaction
+- Webhook handler must be idempotent (Stripe retries on failure)
+- Subscription state must be synced between Stripe and our database
+- Need to handle edge cases: failed payments, plan changes mid-cycle, proration
+
+---
+
+## ADR-003: pgvector for AI-Powered Search
+
+**Status**: Accepted
+
+**Context**: Choose a vector storage and similarity search solution for semantic document search.
+
+**Decision**: pgvector extension on Supabase PostgreSQL.
+
+**Rationale**:
+- Native PostgreSQL extension, no additional infrastructure needed
+- Supabase Pro includes pgvector out of the box
+- Keeps vectors co-located with tenant data (RLS applies to vector queries too)
+- IVFFlat index provides good performance up to ~1M vectors per tenant
+- Cosine similarity search with SQL-native syntax
+- No vendor lock-in to proprietary vector databases
+
+**Alternatives Considered**:
+- Pinecone: Better performance at scale but adds another service, separate billing, and no native tenant isolation (would need namespace-per-tenant)
+- Qdrant: Open source and performant but requires self-hosting another service
+- Supabase Edge Functions + Pinecone: Adds latency and complexity for the AI path
+
+**Consequences**:
+- Embedding dimension fixed at 1536 (text-embedding-3-small). Changing models requires re-embedding all documents
+- IVFFlat index requires periodic `REINDEX` as data grows significantly
+- For >1M documents per tenant, consider HNSW index (higher memory, faster queries)
+- OpenAI API call required for each search query (adds ~200ms latency)
+
+---
+
+## ADR-004: Custom JWT Claims for Tenant Context
+
+**Status**: Accepted
+
+**Context**: Determine how to pass tenant context through the authentication flow so that RLS policies and API endpoints can identify the current tenant.
+
+**Decision**: Store `tenant_id` in Supabase Auth `app_metadata`, which is included in the JWT automatically.
+
+**Rationale**:
+- Supabase Auth includes `app_metadata` in every JWT token by default
+- No additional API calls needed to resolve tenant context
+- RLS policies can read `request.jwt.claims -> 'app_metadata' -> 'tenant_id'`
+- .NET API can extract tenant_id from JWT claims without database lookup
+- Set via database trigger when user joins a tenant (no application code needed for claim updates)
+
+**Alternatives Considered**:
+- Header-based (`X-Tenant-ID`): Requires client to send header on every request, vulnerable to spoofing unless validated server-side
+- Subdomain-based: Good UX but requires wildcard DNS, SSL, and URL parsing on every request. Supabase Auth redirect URLs become complex.
+- Database lookup per request: Adds latency and database load to every authenticated request
+
+**Implementation**:
+- Trigger on `tenant_members` INSERT sets `raw_app_meta_data.tenant_id`
+- User must re-authenticate (or refresh token) after joining a tenant to get updated claims
+- Multi-tenant users: current implementation supports one active tenant per session. Switching tenants requires token refresh.
+
+**Consequences**:
+- Token refresh needed when user switches tenants
+- app_metadata is read-only from client side (only service_role can modify)
+- JWT size increases slightly (~50 bytes for tenant_id claim)
+- Users without a tenant_id claim are redirected to onboarding
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/nextjs-supabase/.morph/examples/saas-nextjs-supabase/spec.md

@@ -0,0 +1,138 @@
+# Multi-Tenant SaaS - Specification
+
+## 1. Overview
+
+Multi-tenant SaaS platform with tenant isolation via PostgreSQL RLS, Stripe subscription billing, team management, and AI-powered semantic search using pgvector.
+
+### 1.1 Objectives
+
+- Tenant isolation at the database level via RLS with custom JWT claims
+- Subscription billing with Stripe (free, starter, pro tiers)
+- Team management with invite flows and role-based access
+- AI-powered document search using OpenAI embeddings + pgvector
+- Dashboard with tenant-scoped metrics and usage tracking
+
+### 1.2 Personas
+
+| Persona | Description |
+|---------|-------------|
+| **Tenant Owner** | Creates tenant, manages billing and team |
+| **Tenant Admin** | Manages team members and settings |
+| **Tenant Member** | Uses the platform (documents, search) |
+| **Platform Admin** | Super admin with cross-tenant visibility |
+
+## 2. Functional Requirements
+
+### 2.1 Tenant Management
+
+| ID | Requirement |
+|----|-------------|
+| TEN-001 | Create tenant during onboarding (name, slug) |
+| TEN-002 | Tenant slug used for identification (unique) |
+| TEN-003 | Tenant settings page (name, logo) |
+| TEN-004 | Tenant status lifecycle: active, past_due, suspended |
+| TEN-005 | tenant_id stored in Supabase Auth app_metadata for JWT claims |
+
+### 2.2 Billing (Stripe)
+
+| ID | Requirement |
+|----|-------------|
+| BILL-001 | Plans: Free, Starter ($29/mo), Pro ($79/mo) |
+| BILL-002 | Stripe Checkout for subscription creation |
+| BILL-003 | Stripe Customer Portal for plan management |
+| BILL-004 | Webhook handling: subscription.created, updated, deleted |
+| BILL-005 | Webhook handling: invoice.payment_failed |
+| BILL-006 | Grace period of 7 days on payment failure before suspension |
+
+### 2.3 Team Management
+
+| ID | Requirement |
+|----|-------------|
+| TEAM-001 | Invite members by email |
+| TEAM-002 | Roles: owner, admin, member |
+| TEAM-003 | Owner can promote/demote members |
+| TEAM-004 | Admin can invite and remove members |
+| TEAM-005 | Member limits per plan (Free: 2, Starter: 5, Pro: 25) |
+
+### 2.4 AI Search (pgvector)
+
+| ID | Requirement |
+|----|-------------|
+| SEARCH-001 | Upload documents with automatic embedding generation |
+| SEARCH-002 | Semantic search across tenant documents |
+| SEARCH-003 | Configurable similarity threshold (default 0.7) |
+| SEARCH-004 | Search results ranked by cosine similarity |
+| SEARCH-005 | Search quota per plan (Free: 100/mo, Starter: 1K/mo, Pro: 10K/mo) |
+
+### 2.5 Dashboard
+
+| ID | Requirement |
+|----|-------------|
+| DASH-001 | Overview: total documents, team size, storage used, plan |
+| DASH-002 | Search usage counter (monthly resets) |
+| DASH-003 | Quick actions: invite member, upload document, search |
+| DASH-004 | Billing status and upgrade prompt |
+
+## 3. Non-Functional Requirements
+
+### 3.1 Performance
+
+| ID | Requirement |
+|----|-------------|
+| PERF-001 | API response < 200ms (P95) for CRUD endpoints |
+| PERF-002 | Semantic search < 500ms (P95) for 100K documents |
+| PERF-003 | pgvector IVFFlat index for sub-linear search time |
+
+### 3.2 Security
+
+| ID | Requirement |
+|----|-------------|
+| SEC-001 | RLS enforced on all tenant-scoped tables |
+| SEC-002 | Stripe webhook signature validation |
+| SEC-003 | Service role key never exposed to frontend |
+| SEC-004 | Rate limiting per tenant (not per user) |
+| SEC-005 | Audit log for team management actions |
+
+### 3.3 Data Isolation
+
+| ID | Requirement |
+|----|-------------|
+| ISO-001 | Single database with tenant_id column on all data tables |
+| ISO-002 | RLS policies read tenant_id from JWT app_metadata |
+| ISO-003 | No cross-tenant data leakage (validated by tests) |
+
+## 4. Plans and Limits
+
+| Feature | Free | Starter | Pro |
+|---------|------|---------|-----|
+| Team Members | 2 | 5 | 25 |
+| Documents | 100 | 1,000 | 10,000 |
+| Storage | 100MB | 1GB | 10GB |
+| Searches/month | 100 | 1,000 | 10,000 |
+| Support | Community | Email | Priority |
+| Price/month | $0 | $29 | $79 |
+
+## 5. Integrations
+
+### 5.1 Stripe
+
+- Customer management (one customer per tenant)
+- Subscription lifecycle
+- Checkout sessions and Customer Portal
+- Webhook handling for payment events
+
+### 5.2 OpenAI
+
+- text-embedding-3-small for document embeddings (1536 dimensions)
+- Called server-side only (API key never on frontend)
+
+### 5.3 Supabase
+
+- Auth with custom claims (tenant_id in app_metadata)
+- PostgreSQL with RLS for tenant isolation
+- pgvector extension for similarity search
+- Storage for document files (per-tenant buckets)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/nextjs-supabase/.morph/examples/saas-nextjs-supabase/tasks.md

@@ -0,0 +1,162 @@
+# Multi-Tenant SaaS - Tasks
+
+## Phase 1: Supabase Setup
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T001 | Create Supabase Pro project with pgvector extension enabled | - | S |
+| T002 | Create tenants table and tenant_members table with RLS policies | T001 | M |
+| T003 | Create auth.tenant_id() helper function for RLS | T001 | S |
+| T004 | Create trigger to set app_metadata.tenant_id on tenant_members INSERT | T002 | M |
+
+## Phase 2: Tenant Data Model
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T005 | Create documents table with tenant_id, embedding column (vector 1536), and RLS | T003 | M |
+| T006 | Create IVFFlat index on documents.embedding for cosine similarity search | T005 | S |
+| T007 | Create search_logs table for usage tracking (searches per month per tenant) | T003 | S |
+| T008 | Create Supabase Storage bucket with per-tenant folder policies | T001 | S |
+
+## Phase 3: .NET API Core
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T009 | Create .NET 10 Minimal API project with Dapper, Npgsql, Stripe.net | - | S |
+| T010 | Configure JWT authentication with Supabase JWT secret and tenant_id claim extraction | T001, T009 | M |
+| T011 | Create TenantMiddleware to extract and validate tenant_id from JWT claims | T010 | M |
+| T012 | Configure CORS and health check endpoints | T009 | S |
+
+## Phase 4: Stripe Billing Integration
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T013 | Create Stripe products and prices (Free, Starter $29, Pro $79) in Stripe Dashboard | - | S |
+| T014 | Implement CreateCheckoutSession endpoint (creates Stripe customer + checkout) | T009, T013 | M |
+| T015 | Implement Stripe Customer Portal endpoint for subscription management | T014 | S |
+| T016 | Implement Stripe webhook handler (subscription.created/updated/deleted, invoice.payment_failed) | T009, T013 | L |
+| T017 | Add plan enforcement middleware (check limits: members, documents, searches) | T016 | M |
+
+## Phase 5: Team Management Endpoints
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T018 | Implement invite member endpoint (create tenant_member, trigger claim update) | T011 | M |
+| T019 | Implement list members, update role, remove member endpoints | T011 | M |
+| T020 | Add member count validation against plan limits | T017 | S |
+
+## Phase 6: AI Search Endpoints
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T021 | Implement document upload endpoint with OpenAI embedding generation | T005, T011 | L |
+| T022 | Implement semantic search endpoint with pgvector cosine similarity | T006, T011 | M |
+| T023 | Implement search quota tracking and enforcement per plan | T007, T017 | M |
+
+## Phase 7: Dashboard Endpoint
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T024 | Implement dashboard metrics endpoint (documents, members, storage, plan, searches) | T011 | M |
+
+## Phase 8: Next.js Frontend Core
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T025 | Create Next.js 15 project with Tailwind CSS, @supabase/ssr | - | S |
+| T026 | Implement Supabase client (browser) and server client with cookie handling | T025, T001 | M |
+| T027 | Create login/signup pages with Supabase Auth | T026 | M |
+| T028 | Create auth callback route and Next.js middleware for protected routes | T026 | M |
+| T029 | Create onboarding page (create tenant for new users without tenant_id) | T026 | M |
+
+## Phase 9: Next.js Dashboard Pages
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T030 | Create TenantProvider context component (reads tenant from session) | T028 | M |
+| T031 | Create dashboard layout with sidebar navigation | T030 | M |
+| T032 | Create dashboard overview page with metric cards | T024, T031 | M |
+| T033 | Create documents page (list, upload, delete) | T021, T031 | M |
+| T034 | Create search page with query input and ranked results | T022, T031 | M |
+
+## Phase 10: Team and Billing Pages
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T035 | Create team management page (list members, invite, remove, change role) | T018, T031 | M |
+| T036 | Create billing page (current plan, upgrade button, Stripe Portal link) | T014, T031 | M |
+| T037 | Create settings page (tenant name, logo) | T031 | S |
+
+## Phase 11: Docker and Deploy
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T038 | Create Dockerfile.api (multi-stage .NET build) | T024 | S |
+| T039 | Create Dockerfile.web (Next.js standalone output) | T037 | S |
+| T040 | Create docker-compose.yml for local development | T038, T039 | S |
+| T041 | Configure EasyPanel services (API + Web) with env vars and health checks | T040 | M |
+
+## Phase 12: Testing and Validation
+
+| ID | Task | Dependencies | Estimate |
+|----|------|--------------|----------|
+| T042 | Write RLS isolation tests (verify no cross-tenant data leakage) | T005 | M |
+| T043 | Write Stripe webhook handler tests (idempotency, signature validation) | T016 | M |
+| T044 | Write search endpoint tests (embedding, similarity threshold, quota) | T022 | M |
+
+## Checkpoints
+
+| Checkpoint | After Tasks | Validation |
+|------------|-------------|------------|
+| CP1 | T004 | Supabase tenant setup complete, auth claims working |
+| CP2 | T008 | Full data model with RLS, pgvector, and storage |
+| CP3 | T012 | API skeleton with JWT auth and tenant middleware |
+| CP4 | T017 | Stripe billing fully integrated with webhooks |
+| CP5 | T020 | Team management working with plan limits |
+| CP6 | T024 | All API endpoints complete (search, dashboard, team, billing) |
+| CP7 | T029 | Auth flow complete (login, signup, onboarding, protected routes) |
+| CP8 | T037 | All frontend pages complete |
+| CP9 | T041 | Docker setup and EasyPanel deployment ready |
+| CP10 | T044 | All tests passing, no cross-tenant leakage |
+
+## Legend
+
+- **S** = Small (< 1h)
+- **M** = Medium (1-3h)
+- **L** = Large (3-8h)
+
+## Execution Order
+
+```
+Supabase Setup (independent):
+T001 -> T002 -> T003 -> T004 (CP1)
+T005 -> T006 -> T007 -> T008 (CP2)
+
+API Core (after T001):
+T009 -> T010 -> T011 -> T012 (CP3)
+
+Billing (after API core):
+T013 -> T014 -> T015 -> T016 -> T017 (CP4)
+
+Team + Search + Dashboard (after billing):
+T018 -> T019 -> T020 (CP5)
+T021 -> T022 -> T023
+T024 (CP6)
+
+Frontend (after T001):
+T025 -> T026 -> T027 -> T028 -> T029 (CP7)
+
+Frontend Pages (after API + auth):
+T030 -> T031 -> T032 -> T033 -> T034
+T035 -> T036 -> T037 (CP8)
+
+Deploy:
+T038 -> T039 -> T040 -> T041 (CP9)
+
+Tests:
+T042 -> T043 -> T044 (CP10)
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/nextjs-supabase/.morph/project.md

@@ -0,0 +1,168 @@
+# Project Context - {PROJECT_NAME}
+
+> Fill in project-specific information for MORPH agents.
+
+## Overview
+
+**Name:** {PROJECT_NAME}
+**Description:** {Brief project description}
+**Type:** Next.js + Supabase Application
+
+---
+
+## Technical Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Frontend | Next.js (App Router) | 15.x |
+| UI Library | shadcn/ui + Tailwind CSS | Latest |
+| Backend | .NET Minimal API | 10.0 |
+| Database | PostgreSQL (Supabase) | 15+ |
+| Data Access | Npgsql + Dapper | Latest |
+| Auth | Supabase Auth | Latest |
+| Storage | Supabase Storage | Latest |
+| Realtime | Supabase Realtime | Latest |
+| Vector Search | pgvector (Supabase) | Latest |
+| Hosting | EasyPanel on VPS | Latest |
+
+---
+
+## Architecture
+
+```
++-------------------------------------------------+
+|              Web (Next.js 15 App Router)         |
++-------------------------------------------------+
+|              API (.NET 10 Minimal API)           |
++-------------------------------------------------+
+|           Data Access (Npgsql + Dapper)          |
++-------------------------------------------------+
+|         Supabase Cloud (DB, Auth, Storage)       |
++-------------------------------------------------+
+```
+
+### Project Structure
+
+```
+src/
+  api/
+    {Project}.Api/              # .NET 10 Minimal API
+      Endpoints/                # Minimal API endpoint groups
+      Services/                 # Business logic
+      Repositories/             # Dapper queries
+      Models/                   # Entities, DTOs (records)
+  web/
+    app/                        # Next.js App Router pages
+    components/                 # React components (shadcn/ui)
+    lib/                        # Utilities, Supabase client
+    hooks/                      # Custom React hooks
+
+supabase/
+  migrations/                   # SQL migrations
+  seeds/                        # Seed data
+  policies/                     # RLS policies
+
+tests/
+  {Project}.Tests.Unit/         # .NET unit tests (xUnit)
+  {Project}.Tests.Integration/  # .NET integration tests
+  web/__tests__/                # Vitest + Testing Library
+```
+
+---
+
+## Conventions
+
+### Naming
+
+- **C# Classes:** PascalCase (e.g., `ReportScheduleService`)
+- **C# Interfaces:** I + PascalCase (e.g., `IReportScheduleService`)
+- **C# Methods:** PascalCase, async with Async suffix (e.g., `GetByIdAsync`)
+- **C# Variables:** camelCase (e.g., `reportSchedule`)
+- **C# Private fields:** _camelCase (e.g., `_repository`)
+- **TypeScript Functions/Variables:** camelCase (e.g., `getReportSchedule`)
+- **TypeScript Components:** PascalCase (e.g., `ReportScheduleCard`)
+- **TypeScript Types/Interfaces:** PascalCase (e.g., `ReportScheduleDto`)
+- **SQL Tables:** snake_case (e.g., `report_schedules`)
+- **SQL Columns:** snake_case (e.g., `created_at`)
+
+### Code Style
+
+- C#: Primary constructors (C# 14), records for DTOs, sealed classes by default
+- TypeScript: Strict mode, prefer `const`, arrow functions for components
+- SQL: Lowercase keywords, explicit column lists (never SELECT *)
+
+### Documentation
+
+- Code in English
+- XML comments on public C# methods
+- JSDoc on exported TypeScript functions
+
+---
+
+## Supabase Resources
+
+| Resource | Purpose | Tier |
+|----------|---------|------|
+| PostgreSQL | Primary database | Pro / Free |
+| Auth | Authentication (OAuth) | Included |
+| Storage | File uploads | Included |
+| Realtime | WebSocket subscriptions | Included |
+| pgvector | Vector search (if needed) | Extension |
+
+### Auth Configuration
+
+- **Provider:** Supabase Auth
+- **OAuth:** Google + GitHub
+- **Session:** @supabase/ssr (server-side cookies)
+- **JWT:** Validated in .NET API via Supabase JWT secret
+
+### Cost Estimates
+
+| Environment | Monthly Cost |
+|-------------|-------------|
+| Dev (Supabase Free + VPS) | ~$6 |
+| Prod (Supabase Pro + VPS) | ~$31 |
+
+---
+
+## External Integrations
+
+| Service | Purpose | Auth Method |
+|---------|---------|-------------|
+| Supabase | DB, Auth, Storage | Service Role Key |
+| {Service} | {Purpose} | {Method} |
+
+---
+
+## Development Guidelines
+
+### Git Flow
+
+- **main** -- Production
+- **develop** -- Development
+- **feature/{name}** -- Features
+
+### Commit Convention
+
+```
+{type}({scope}): {message}
+
+Types: feat, fix, docs, style, refactor, test, chore
+```
+
+### PR Requirements
+
+- [ ] Tests passing
+- [ ] Code review approved
+- [ ] No conflicts
+- [ ] Linked to work item
+
+---
+
+## Notes
+
+{Add project-specific notes here}
+
+---
+
+*Generated by MORPH Framework*