@etus/bhono-app 0.1.5 → 0.1.7

package/templates/base/docs/architecture/c4-component.md

@@ -0,0 +1,309 @@
+# C4 Model - Level 3: Component Diagrams
+
+> Shows how containers are made up of components and their relationships.
+
+## Backend Components (Hono API)
+
+```mermaid
+C4Component
+    title Component Diagram - Hono API
+
+    Container_Boundary(api, "Hono API") {
+        Component(middleware, "Middleware Stack", "Hono Middleware", "Request processing pipeline")
+        Component(routes, "Route Handlers", "OpenAPI Routes", "HTTP endpoint handlers")
+        Component(services, "Service Layer", "TypeScript", "Business logic")
+        Component(auth, "Auth Module", "Guards + RBAC", "Authorization checks")
+        Component(db, "Database Layer", "SQL Helpers", "D1 data access")
+        Component(lib, "Utilities", "TypeScript", "Shared utilities")
+    }
+
+    ContainerDb(d1, "D1", "SQLite")
+    ContainerDb(kv, "KV", "Sessions")
+    ContainerDb(r2, "R2", "Files")
+
+    Rel(middleware, routes, "Passes request")
+    Rel(routes, services, "Calls")
+    Rel(routes, auth, "Checks permissions")
+    Rel(services, db, "Queries")
+    Rel(services, lib, "Uses")
+    Rel(db, d1, "SQL")
+    Rel(middleware, kv, "Sessions")
+    Rel(services, r2, "Files")
+```
+
+## Middleware Stack [HIGH]
+
+| Order | Middleware | File | Purpose |
+|-------|------------|------|---------|
+| 1 | Error Handler | `middleware/error-handler.ts` | Global error handling |
+| 2 | Request Context | `middleware/request-context.ts` | Transaction ID, timing |
+| 3 | Request Logger | `middleware/request-logger.ts` | Structured logging |
+| 4 | CORS | `middleware/cors.ts` | Cross-origin requests |
+| 5 | Rate Limiter | `middleware/rate-limit.ts` | Throttling protection |
+| 6 | Session Auth | `middleware/auth.ts` | Session validation |
+| 7 | Account Context | `middleware/account.ts` | Multi-tenant context |
+
+### Middleware Flow
+
+```
+Request
+   │
+   ▼
+┌──────────────────┐
+│  Error Handler   │ ◄── Catches all errors
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Request Context  │ ◄── Adds transactionId, startTime
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Request Logger   │ ◄── Logs request details
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│      CORS        │ ◄── Handles preflight
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│   Rate Limiter   │ ◄── Throttles excessive requests
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│   Session Auth   │ ◄── Validates session cookie
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│ Account Context  │ ◄── Sets current account
+└────────┬─────────┘
+         │
+         ▼
+    Route Handler
+```
+
+## Route Handlers [HIGH]
+
+| Module | Path | Endpoints | Purpose |
+|--------|------|-----------|---------|
+| Auth | `/auth/*` | 6 | Authentication flows |
+| Users | `/api/users/*` | 8 | User CRUD + bulk |
+| Accounts | `/api/accounts/*` | 6 | Account CRUD |
+| Invitations | `/api/invitations/*` | 3 | Team invitations |
+| Audits | `/api/audits/*` | 1 | Audit log queries |
+| Storage | `/api/storage/*` | 3 | File operations |
+| Health | `/health/*` | 3 | Health probes |
+
+### Route Structure
+
+```
+src/server/routes/
+├── index.ts          # API router composition
+├── schemas.ts        # Shared schemas
+├── openapi.ts        # OpenAPI config
+├── api.ts            # API router export
+├── auth/
+│   ├── index.ts      # Auth router
+│   ├── routes.ts     # Route definitions (OpenAPI)
+│   ├── handlers.ts   # Request handlers
+│   └── schemas.ts    # Auth schemas
+├── users/
+│   ├── index.ts
+│   ├── routes.ts
+│   ├── handlers.ts
+│   └── schemas.ts
+├── accounts/
+│   ├── index.ts
+│   ├── routes.ts
+│   ├── handlers.ts
+│   └── schemas.ts
+├── invitations/
+│   ├── index.ts
+│   ├── routes.ts
+│   ├── handlers.ts
+│   └── schemas.ts
+├── audits/
+│   ├── index.ts
+│   ├── routes.ts
+│   ├── handlers.ts
+│   └── schemas.ts
+├── storage/
+│   ├── index.ts
+│   ├── routes.ts
+│   ├── handlers.ts
+│   └── schemas.ts
+└── health/
+    ├── index.ts
+    ├── routes.ts
+    └── handlers.ts
+```
+
+## Service Layer [HIGH]
+
+| Service | File | Responsibilities |
+|---------|------|------------------|
+| AuthService | `services/auth.ts` | OAuth flow, session management, token refresh |
+| UsersService | `services/users.ts` | User CRUD, account memberships |
+| AccountsService | `services/accounts.ts` | Account CRUD, member management |
+| InvitationsService | `services/invitations.ts` | Invitation lifecycle |
+| AuditsService | `services/audits.ts` | Audit log queries |
+
+### Service Pattern
+
+```typescript
+// Each service follows this pattern:
+export class UsersService {
+  constructor(
+    private db: D1Database,
+    private context: RequestContext
+  ) {}
+
+  async list(accountId: string, pagination: Pagination): Promise<PaginatedUsers> {
+    // Business logic + DB queries
+  }
+
+  async create(data: CreateUser): Promise<User> {
+    // Validation + creation + audit logging
+  }
+}
+```
+
+## Auth Module [HIGH]
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| Roles | `auth/roles.ts` | Role definitions and hierarchy |
+| Permissions | `auth/permissions.ts` | Permission constants |
+| Guards | `auth/guards.ts` | Authorization checks |
+
+### Role Hierarchy
+
+```
+ADMIN
+  └── MANAGER
+       └── EDITOR
+            └── AUTHOR
+                 └── VIEWER
+
+BILLING  (separate branch)
+ANALYTICS (separate branch)
+```
+
+### Guard Functions
+
+| Guard | Purpose |
+|-------|---------|
+| `requireAuth()` | Ensures user is authenticated |
+| `requireRole(role)` | Checks user has role or higher |
+| `requirePermission(perm)` | Checks specific permission |
+| `requireSuperAdmin()` | Checks super admin flag |
+| `requireAccountMember()` | Verifies account membership |
+
+## Database Layer [HIGH]
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| SQL Helpers | `db/sql.ts` | `queryOne`, `queryAll`, `execute` |
+| Record Types | `db/records.ts` | TypeScript types for SQL results |
+| Client | `db/client.ts` | D1 client wrapper |
+| Seed | `db/seed.ts` | Test data generator |
+
+### SQL Helper Pattern
+
+```typescript
+// Type-safe SQL execution
+const user = await queryOne<UserRecord>(db,
+  'SELECT * FROM users WHERE id = ?',
+  [userId]
+);
+
+const users = await queryAll<UserRecord>(db,
+  'SELECT * FROM users WHERE account_id = ? LIMIT ? OFFSET ?',
+  [accountId, limit, offset]
+);
+
+await execute(db,
+  'UPDATE users SET name = ? WHERE id = ?',
+  [name, userId]
+);
+```
+
+## Utility Libraries [HIGH]
+
+| Library | File | Purpose |
+|---------|------|---------|
+| OAuth | `lib/oauth.ts` | Google OAuth helpers |
+| Session | `lib/session.ts` | Session create/validate/destroy |
+| Tokens | `lib/tokens.ts` | Refresh token management |
+| Audit | `lib/audit.ts` | Audit log creation |
+| Email | `lib/email.ts` | SendGrid integration |
+| Errors | `lib/errors.ts` | Custom error classes |
+| Pagination | `lib/pagination.ts` | Pagination helpers |
+| R2 Storage | `lib/r2-storage.ts` | File storage helpers |
+
+---
+
+## Frontend Components (React SPA)
+
+```mermaid
+C4Component
+    title Component Diagram - React SPA
+
+    Container_Boundary(spa, "React SPA") {
+        Component(router, "TanStack Router", "File-based routing", "Client-side navigation")
+        Component(auth, "Auth Provider", "React Context", "Authentication state")
+        Component(query, "React Query", "Data fetching", "Server state management")
+        Component(routes, "Route Components", "React", "Page components")
+        Component(ui, "UI Components", "Radix + Tailwind", "Reusable components")
+        Component(hooks, "Custom Hooks", "React", "Shared logic")
+    }
+
+    Container(api, "Hono API", "Backend")
+
+    Rel(router, routes, "Renders")
+    Rel(routes, auth, "Uses")
+    Rel(routes, query, "Fetches data")
+    Rel(routes, ui, "Composes")
+    Rel(routes, hooks, "Uses")
+    Rel(query, api, "REST calls")
+```
+
+## Frontend Route Structure [HIGH]
+
+```
+src/client/routes/
+├── __root.tsx              # Root layout
+├── index.tsx               # Landing page (/)
+├── login.tsx               # Login page (/login)
+├── $.tsx                   # 404 catch-all
+├── invite.$token.tsx       # Invitation acceptance
+└── _authenticated/         # Protected routes
+    ├── dashboard.tsx       # Dashboard (/dashboard)
+    ├── account.tsx         # Account page (/account)
+    ├── team.tsx            # Team management (/team)
+    ├── settings.tsx        # User settings (/settings)
+    └── integrations.tsx    # Integrations (/integrations)
+```
+
+## UI Component Library [HIGH]
+
+| Category | Components |
+|----------|------------|
+| **Layout** | Sidebar |
+| **Feedback** | Sonner (Toasts), Loading Skeleton, Error Fallback |
+| **Forms** | Input, Label, Form, Button |
+| **Display** | Card, Badge, Avatar, Tabs |
+| **Overlay** | Dialog |
+| **Utility** | Separator, Skeleton |
+
+## Custom Hooks [HIGH]
+
+| Hook | File | Purpose |
+|------|------|---------|
+| `useAuth` | `hooks/use-auth.ts` | Authentication state + methods |
+| `useTheme` | `hooks/use-theme.tsx` | Theme (dark/light) management |

package/templates/base/docs/architecture/c4-container.md

@@ -0,0 +1,183 @@
+# C4 Model - Level 2: Container Diagram
+
+> Shows the high-level shape of the software architecture and how responsibilities are distributed.
+
+## Container Diagram
+
+```mermaid
+C4Container
+    title Container Diagram - BHono Platform
+
+    Person(user, "User", "SaaS platform user")
+
+    System_Boundary(bhono, "BHono Platform") {
+        Container(spa, "React SPA", "React 19, TanStack Router", "Single-page application providing the user interface")
+        Container(api, "Hono API", "Hono.js, TypeScript", "REST API handling business logic and data access")
+        ContainerDb(d1, "D1 Database", "SQLite at Edge", "Stores users, accounts, invitations, audit logs")
+        ContainerDb(kv, "KV Store", "Cloudflare KV", "Stores user sessions")
+        ContainerDb(r2, "R2 Storage", "Cloudflare R2", "Stores uploaded files")
+    }
+
+    System_Ext(google, "Google OAuth", "Identity provider")
+    System_Ext(sendgrid, "SendGrid", "Email service")
+
+    Rel(user, spa, "Uses", "HTTPS")
+    Rel(spa, api, "API calls", "REST/JSON")
+    Rel(api, d1, "Reads/Writes", "SQL")
+    Rel(api, kv, "Sessions", "KV API")
+    Rel(api, r2, "Files", "R2 API")
+    Rel(api, google, "Auth", "OAuth 2.0")
+    Rel(api, sendgrid, "Emails", "REST API")
+```
+
+## Container Details
+
+### React SPA [HIGH]
+
+| Attribute | Value |
+|-----------|-------|
+| **Technology** | React 19, TanStack Router, TanStack Query |
+| **Deployment** | Static assets served from Cloudflare R2/Edge |
+| **Purpose** | User interface for the SaaS platform |
+| **Build Output** | `dist/` directory |
+
+**Responsibilities:**
+- Render user interface
+- Handle client-side routing
+- Manage client state
+- Call backend API
+- Handle authentication redirects
+
+**Key Dependencies:**
+- `react` - UI library
+- `@tanstack/react-router` - File-based routing
+- `@tanstack/react-query` - Data fetching/caching
+- `react-hook-form` - Form handling
+- `tailwindcss` - Styling
+- `radix-ui/*` - Accessible UI primitives
+
+### Hono API [HIGH]
+
+| Attribute | Value |
+|-----------|-------|
+| **Technology** | Hono.js 4.x, TypeScript, Zod |
+| **Deployment** | Cloudflare Workers |
+| **Purpose** | REST API for all backend operations |
+| **Entry Point** | `src/server/index.ts` |
+
+**Responsibilities:**
+- Handle HTTP requests
+- Authenticate/authorize users
+- Execute business logic
+- Access data stores
+- Generate OpenAPI documentation
+
+**Key Dependencies:**
+- `hono` - Web framework
+- `@hono/zod-openapi` - OpenAPI integration
+- `zod` - Request/response validation
+- `uuidv7` - ID generation
+
+### D1 Database [HIGH]
+
+| Attribute | Value |
+|-----------|-------|
+| **Technology** | Cloudflare D1 (SQLite) |
+| **Binding** | `DB` |
+| **Schema** | `schema.sql` |
+
+**Tables:**
+| Table | Purpose |
+|-------|---------|
+| `users` | User profiles and authentication |
+| `accounts` | Workspaces/organizations |
+| `user_accounts` | User-account memberships with roles |
+| `invitations` | Pending team invitations |
+| `refresh_tokens` | Token storage for session refresh |
+| `audit_logs` | All state change audit trail |
+
+### KV Store [HIGH]
+
+| Attribute | Value |
+|-----------|-------|
+| **Technology** | Cloudflare KV |
+| **Binding** | `SESSIONS` |
+| **Purpose** | Session storage |
+
+**Data Stored:**
+- Session ID → User session data (JSON)
+- Session expiration via TTL
+
+### R2 Storage [HIGH]
+
+| Attribute | Value |
+|-----------|-------|
+| **Technology** | Cloudflare R2 |
+| **Binding** | `R2_BUCKET` |
+| **Purpose** | File storage |
+
+**Usage:**
+- User-uploaded files
+- Account-scoped file storage
+- Presigned URL support for secure uploads
+
+## Inter-Container Communication
+
+| From | To | Protocol | Purpose |
+|------|-----|----------|---------|
+| React SPA | Hono API | REST/JSON | All data operations |
+| Hono API | D1 | SQL | Data persistence |
+| Hono API | KV | KV API | Session management |
+| Hono API | R2 | R2 API | File operations |
+| Hono API | Google | OAuth 2.0 | Authentication |
+| Hono API | SendGrid | REST | Email delivery |
+
+## Deployment Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                 Cloudflare Edge Network                 │
+│  ┌──────────────────────────────────────────────────┐   │
+│  │              Cloudflare Worker                   │   │
+│  │  ┌─────────────────┐  ┌─────────────────────┐    │   │
+│  │  │   Static Assets │  │     Hono API        │    │   │
+│  │  │   (React SPA)   │  │   (Server Logic)    │    │   │
+│  │  └─────────────────┘  └──────────┬──────────┘    │   │
+│  └──────────────────────────────────┼───────────────┘   │
+│                                     │                   │
+│     ┌───────────┬───────────────────┼───────────────┐   │
+│     │           │                   │               │   │
+│     ▼           ▼                   ▼               │   │
+│  ┌─────┐    ┌─────┐            ┌─────────┐          │   │
+│  │ D1  │    │ KV  │            │   R2    │          │   │
+│  └─────┘    └─────┘            └─────────┘          │   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Request Flow
+
+### Authenticated Request
+
+```
+1. User → React SPA: Navigate to /dashboard
+2. React SPA → Hono API: GET /api/users (with session cookie)
+3. Hono API → KV: Validate session
+4. Hono API → D1: Query users for account
+5. D1 → Hono API: User data
+6. Hono API → React SPA: JSON response
+7. React SPA → User: Render dashboard
+```
+
+### Authentication Flow
+
+```
+1. User → React SPA: Click "Login with Google"
+2. React SPA → Hono API: GET /auth/login
+3. Hono API → User: Redirect to Google OAuth
+4. User → Google: Authorize
+5. Google → Hono API: GET /auth/callback (with code)
+6. Hono API → Google: Exchange code for tokens
+7. Hono API → D1: Create/update user
+8. Hono API → KV: Create session
+9. Hono API → User: Set cookie, redirect to app
+```

package/templates/base/docs/architecture/c4-context.md

@@ -0,0 +1,106 @@
+# C4 Model - Level 1: System Context
+
+> Shows how BHono fits into the world around it.
+
+## System Context Diagram
+
+```mermaid
+C4Context
+    title System Context Diagram - BHono SaaS Platform
+
+    Person(user, "User", "A person who uses the SaaS application")
+    Person(admin, "Admin", "Account administrator managing team members")
+
+    System(bhono, "BHono Platform", "Multi-tenant SaaS application with user management, team collaboration, and file storage")
+
+    System_Ext(google, "Google OAuth", "Identity provider for authentication")
+    System_Ext(sendgrid, "SendGrid", "Email delivery service for invitations")
+
+    Rel(user, bhono, "Uses", "HTTPS")
+    Rel(admin, bhono, "Manages teams", "HTTPS")
+    Rel(bhono, google, "Authenticates users", "OAuth 2.0")
+    Rel(bhono, sendgrid, "Sends emails", "REST API")
+```
+
+## Context Description
+
+| Element | Type | Description | Confidence |
+|---------|------|-------------|------------|
+| **User** | Person | End user of the SaaS platform. Can belong to multiple accounts (workspaces). | HIGH |
+| **Admin** | Person | Account administrator with elevated permissions to manage team members and invitations. | HIGH |
+| **BHono Platform** | System | The main application - a multi-tenant SaaS platform deployed on Cloudflare Workers edge. | HIGH |
+| **Google OAuth** | External System | Google's OAuth 2.0 service used for user authentication. | HIGH |
+| **SendGrid** | External System | Email delivery service for sending team invitations. | HIGH |
+
+## System Responsibilities
+
+### BHono Platform
+
+The core system provides:
+
+| Capability | Description | Confidence |
+|------------|-------------|------------|
+| **User Authentication** | OAuth 2.0 flow with Google, session management via cookies | HIGH |
+| **Multi-tenancy** | Users can belong to multiple Accounts with different roles | HIGH |
+| **Team Collaboration** | Invite team members via email, manage permissions | HIGH |
+| **File Storage** | Upload/download files via R2 storage | HIGH |
+| **Audit Logging** | Track all state changes for compliance | HIGH |
+| **API Access** | REST API with OpenAPI documentation | HIGH |
+
+## External System Dependencies
+
+### Google OAuth [HIGH]
+
+- **Purpose**: User authentication
+- **Protocol**: OAuth 2.0 with PKCE
+- **Endpoints Used**:
+  - `https://accounts.google.com/o/oauth2/v2/auth` - Authorization
+  - `https://oauth2.googleapis.com/token` - Token exchange
+  - `https://www.googleapis.com/oauth2/v3/userinfo` - User info
+- **Data Exchanged**: User email, name, avatar URL, Google ID
+
+### SendGrid [HIGH]
+
+- **Purpose**: Email delivery for invitations
+- **Protocol**: REST API
+- **Endpoints Used**: SendGrid Mail Send API
+- **Data Exchanged**: Recipient email, invitation details, sender info
+
+## User Roles
+
+| Role | Description | Confidence |
+|------|-------------|------------|
+| **ADMIN** | Full account access, can manage all members and settings | HIGH |
+| **MANAGER** | Can manage team members (invite, remove) | HIGH |
+| **EDITOR** | Can edit all content | HIGH |
+| **AUTHOR** | Can create and edit own content | HIGH |
+| **VIEWER** | Read-only access | HIGH |
+| **BILLING** | Access to billing information | HIGH |
+| **ANALYTICS** | Access to analytics and audit logs | HIGH |
+
+## Non-Functional Requirements
+
+| Requirement | Target | Implementation | Confidence |
+|-------------|--------|----------------|------------|
+| **Latency** | <100ms globally | Cloudflare Edge deployment | HIGH |
+| **Availability** | 99.9%+ | Cloudflare Workers SLA | HIGH |
+| **Security** | OAuth 2.0, RBAC | Google OAuth + Guards | HIGH |
+| **Compliance** | Audit trail | audit_logs table | HIGH |
+| **Multi-region** | Global | Cloudflare Edge network | HIGH |
+
+## Data Flow Overview
+
+```
+┌─────────┐     HTTPS      ┌──────────────────┐
+│  User   │───────────────▶│  BHono Platform  │
+└─────────┘                └────────┬─────────┘
+                                    │
+                    ┌───────────────┼───────────────┐
+                    │               │               │
+                    ▼               ▼               ▼
+            ┌───────────┐   ┌───────────┐   ┌───────────┐
+            │  Google   │   │  SendGrid │   │ Cloudflare│
+            │  OAuth    │   │           │   │ Services  │
+            └───────────┘   └───────────┘   └───────────┘
+                                            D1 | KV | R2
+```

package/templates/base/docs/architecture/data-requirements.md

@@ -1,7 +1,7 @@
 # Data Requirements Document (DRD)
 
 ## 1. Objetivo e escopo
-Este documento define os requisitos de dados do projeto, cobrindo o modelo relacional (D1/SQLite), armazenamento de sessao (KV) e objetos (R2). Serve como referencia para manutencao, auditoria e eventual migracao para SQL puro.
+Este documento define os requisitos de dados do projeto, cobrindo o modelo relacional (D1/SQLite), armazenamento de sessao (KV) e objetos (R2). Serve como referencia para manutencao, auditoria e evolucao do SQL puro.
 
 ## 2. Componentes de armazenamento
 - D1 (SQLite): armazenamento relacional principal.
@@ -102,8 +102,9 @@ Principais entidades:
 - Requisito: manter procedimento de backup/restore do D1 (ex.: exportacao periodica) e verificar restauracao.
 - KV e R2 devem ter estrategia de recuperacao alinhada com RPO/RTO desejados.
 
-## 12. Consideracoes para migracao para SQL puro
+## 12. Consideracoes para SQL puro (sem migrations)
 - Todas as queries devem ser parametrizadas para evitar SQL injection.
 - Manter mapeadores de resultado (ex.: validacao via Zod) para preservar contratos tipados.
 - Centralizar SQL em um modulo `db` e reutilizar modelos do ERD.
-- Implementar migracoes em SQL (ou manter ferramenta atual apenas para migrar schema).
+- `schema.sql` e a fonte de verdade do schema e deve ser aplicado via `wrangler d1 execute`.
+- `seed.sql` e gerado a partir de `src/server/db/seed.ts` e aplicado apos o bootstrap quando necessario.

package/templates/base/docs/architecture/db-bootstrap.md

@@ -0,0 +1,39 @@
+# Database Bootstrap (schema.sql)
+
+## Objetivo
+O boilerplate nao usa migrations. O schema do D1 e versionado em `schema.sql` e aplicado via `wrangler d1 execute`. O seed e gerado em `seed.sql` a partir de `src/server/db/seed.ts`.
+
+## Arquivos
+- `schema.sql` - fonte de verdade do schema
+- `src/server/db/seed.ts` - gerador de seed
+- `seed.sql` - output do seed (gerado)
+
+## Fluxos recomendados
+### Local
+```bash
+# aplicar schema
+pnpm db:schema:local
+
+# gerar e aplicar seed
+pnpm db:seed:local
+
+# reset completo (schema + seed)
+pnpm db:reset:local
+```
+
+### Remoto (opcional)
+```bash
+# aplicar schema
+pnpm db:schema:remote
+
+# gerar e aplicar seed
+pnpm db:seed:remote
+
+# reset completo (schema + seed)
+pnpm db:reset:remote
+```
+
+## Notas
+- `schema.sql` deve ser atualizado a cada mudanca estrutural.
+- `seed.sql` deve ser re-gerado apos alteracoes em `seed.ts`.
+- As migrations nao sao usadas neste boilerplate para manter o fluxo simples.