backend-saas

Files (4)

• SKILL.md
• api-structure.md · examples/
• csharp.md · examples/
• python.md · examples/

SKILL.md (first lines)

# SaaS Backend Development

## When to Use

- Building backend APIs
- Designing multi-tenant systems
- Implementing authentication/authorization
- Setting up observability
- Planning for scale
- Handling background jobs

## API Design

### RESTful Conventions

| Method | Path | Action | Status Codes |
|--------|------|--------|--------------|
| GET | /resources | List all | 200, 204 |
| GET | /resources/:id | Get one | 200, 404 |
| POST | /resources | Create | 201, 400, 422 |
| PUT | /resources/:id | Replace | 200, 404 |
| PATCH | /resources/:id | Update | 200, 404 |
| DELETE | /resources/:id | Remove | 204, 404 |

### Response Format

```json
{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}
```

### Error Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is invalid",
    "details": [
      { "field": "email", "message": "must be a valid email" }
    ]
  }
}
```

### Pagination

```
GET /api/users?page=2&per_page=20
GET /api/users?cursor=abc123&limit=20  (cursor-based)
```

### Filtering and Sorting

```
GET /api/users?status=active&role=admin
GET /api/users?sort=-created_at,name  (- for descending)
```

## Multi-Tenancy

### Strategies

| Strategy | Isolation | Complexity | Cost |
|----------|-----------|------------|------|
| **Shared DB, Shared Schema** | Low | Low | Low |
| **Shared DB, Separate Schema** | Medium | Medium | Medium |
| **Separate Database** | High | High | High |

### Row-Level Security (Shared Schema)

```sql
-- Every table has tenant_id
CREATE TABLE users (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    email VARCHAR(255) NOT NULL,
    -- ...
);

-- RLS policy
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON users
    USING (tenant_id = current_setting('app.tenant_id')::UUID);

-- Set tenant context per request
SET app.tenant_id = 'tenant-uuid-here';
```

### Application-Level Filtering

```python
class TenantMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # Extract tenant from subdomain, header, or JWT
        tenant_id = self.extract_tenant(request)
        request.tenant_id = tenant_id
        return self.get_response(request)

class TenantQuerySet:
    def get_queryset(self):
        return super().get_queryset().filter(
            tenant_id=self.request.tenant_id
        )
```

## Authentication & Authorization

### JWT Structure

From nathan-oakes/AI-DLC, MIT.