@etus/bhono-app 0.1.5 → 0.1.7

package/templates/base/docs/architecture/dependencies.md

@@ -0,0 +1,327 @@
+# Module Dependencies - BHono Platform
+
+> Service and module dependency map showing how components interact.
+
+## Dependency Overview
+
+```mermaid
+graph TD
+    subgraph "Entry Points"
+        ServerEntry[src/server/index.ts]
+        ClientEntry[src/client/main.tsx]
+    end
+
+    subgraph "Server Layer"
+        Middleware[middleware/]
+        Routes[routes/]
+        Services[services/]
+        Auth[auth/]
+        DB[db/]
+        Lib[lib/]
+    end
+
+    subgraph "Client Layer"
+        Router[router.ts]
+        ClientRoutes[routes/]
+        Components[components/]
+        Hooks[hooks/]
+    end
+
+    subgraph "Shared Layer"
+        Schemas[shared/schemas/]
+        Types[shared/types/]
+    end
+
+    subgraph "External"
+        D1[(D1 Database)]
+        KV[(KV Store)]
+        R2[(R2 Storage)]
+        Google[Google OAuth]
+        SendGrid[SendGrid]
+    end
+
+    ServerEntry --> Middleware
+    ServerEntry --> Routes
+    Middleware --> Auth
+    Middleware --> Lib
+    Routes --> Services
+    Routes --> Schemas
+    Services --> DB
+    Services --> Lib
+    Auth --> DB
+    DB --> D1
+    Lib --> KV
+    Lib --> R2
+    Lib --> Google
+    Lib --> SendGrid
+
+    ClientEntry --> Router
+    Router --> ClientRoutes
+    ClientRoutes --> Components
+    ClientRoutes --> Hooks
+    Components --> Types
+    Hooks --> Types
+    Hooks --> Schemas
+```
+
+---
+
+## Server Dependencies [HIGH]
+
+### Middleware Layer
+
+| Module | Dependencies | Purpose |
+|--------|--------------|---------|
+| `error-handler.ts` | `lib/errors` | Global error handling |
+| `request-context.ts` | `uuidv7` | Transaction ID generation |
+| `request-logger.ts` | `request-context` | Structured logging |
+| `cors.ts` | `hono/cors` | CORS configuration |
+| `rate-limit.ts` | None | In-memory rate limiting |
+| `auth.ts` | `lib/session`, `auth/guards` | Session validation |
+| `account.ts` | `db/sql`, `auth/guards` | Account context |
+
+```mermaid
+graph LR
+    Request[Request] --> EH[Error Handler]
+    EH --> RC[Request Context]
+    RC --> RL[Request Logger]
+    RL --> CORS[CORS]
+    CORS --> Rate[Rate Limiter]
+    Rate --> Auth[Session Auth]
+    Auth --> Acc[Account Context]
+    Acc --> Handler[Route Handler]
+```
+
+### Routes Layer
+
+| Route Module | Service Dependencies | Schema Dependencies |
+|--------------|---------------------|---------------------|
+| `auth/` | `AuthService` | `auth/schemas` |
+| `users/` | `UsersService` | `users/schemas`, `shared/schemas/user` |
+| `accounts/` | `AccountsService` | `accounts/schemas`, `shared/schemas/account` |
+| `invitations/` | `InvitationsService` | `invitations/schemas`, `shared/schemas/invitation` |
+| `audits/` | `AuditsService` | `audits/schemas` |
+| `storage/` | R2 direct | `storage/schemas` |
+| `health/` | D1 direct | None |
+
+### Services Layer
+
+| Service | Dependencies | External |
+|---------|--------------|----------|
+| `AuthService` | `db/sql`, `lib/oauth`, `lib/session`, `lib/tokens` | Google OAuth, KV |
+| `UsersService` | `db/sql`, `lib/audit` | D1 |
+| `AccountsService` | `db/sql`, `lib/audit` | D1 |
+| `InvitationsService` | `db/sql`, `lib/email`, `lib/tokens` | D1, SendGrid |
+| `AuditsService` | `db/sql` | D1 |
+
+### Library Layer
+
+| Library | Dependencies | External Services |
+|---------|--------------|-------------------|
+| `oauth.ts` | None | Google OAuth APIs |
+| `session.ts` | None | Cloudflare KV |
+| `tokens.ts` | `crypto` | None |
+| `email.ts` | None | SendGrid API |
+| `audit.ts` | `db/sql` | D1 |
+| `pagination.ts` | None | None |
+| `errors.ts` | None | None |
+| `r2-storage.ts` | None | Cloudflare R2 |
+
+### Auth Layer
+
+| Module | Dependencies | Purpose |
+|--------|--------------|---------|
+| `roles.ts` | None | Role hierarchy definition |
+| `permissions.ts` | `roles` | Permission constants |
+| `guards.ts` | `roles`, `permissions` | Authorization checks |
+
+```mermaid
+graph TD
+    Guards[guards.ts] --> Roles[roles.ts]
+    Guards --> Permissions[permissions.ts]
+    Permissions --> Roles
+```
+
+### Database Layer
+
+| Module | Dependencies | Purpose |
+|--------|--------------|---------|
+| `sql.ts` | D1 binding | Query helpers |
+| `records.ts` | None | Type definitions |
+| `client.ts` | D1 binding | Client wrapper |
+| `seed.ts` | `sql.ts` | Test data generation |
+
+---
+
+## Client Dependencies [HIGH]
+
+### Route Dependencies
+
+| Route | Component Dependencies | Hook Dependencies |
+|-------|----------------------|-------------------|
+| `__root.tsx` | `Sonner`, `ErrorBoundary` | `useTheme` |
+| `_authenticated.tsx` | `Sidebar`, `LoadingSkeleton` | `useAuth` |
+| `login.tsx` | `Button`, `Card`, `Icons` | None |
+| `dashboard.tsx` | `Card`, `Badge` | `useAuth` |
+| `team.tsx` | `Card`, `Dialog`, `Avatar` | `useAuth` |
+| `settings.tsx` | `Tabs`, `Form`, `Input` | `useAuth` |
+| `account.tsx` | `Card`, `Badge` | `useAuth` |
+| `integrations.tsx` | `Card`, `Dialog`, `Badge` | `useAuth` |
+
+### Component Dependencies
+
+| Component | External Dependencies |
+|-----------|----------------------|
+| `Button` | `class-variance-authority`, `@radix-ui/react-slot` |
+| `Dialog` | `@radix-ui/react-dialog` |
+| `Tabs` | `@radix-ui/react-tabs` |
+| `Avatar` | `@radix-ui/react-avatar` |
+| `Form` | `react-hook-form`, `@hookform/resolvers/zod` |
+| `Sonner` | `sonner` |
+| `Sidebar` | `lucide-react` |
+
+### Hook Dependencies
+
+| Hook | Dependencies |
+|------|--------------|
+| `useAuth` | `@tanstack/react-query`, `shared/types/auth` |
+| `useTheme` | React Context |
+
+---
+
+## Shared Dependencies [HIGH]
+
+### Schemas
+
+| Schema | Used By |
+|--------|---------|
+| `user.ts` | `server/routes/users`, `client/hooks/use-auth` |
+| `account.ts` | `server/routes/accounts`, `client/routes/account` |
+| `invitation.ts` | `server/routes/invitations`, `client/routes/team` |
+| `profile.ts` | `server/routes/users`, `client/routes/settings` |
+| `webhook.ts` | `client/routes/integrations` |
+
+### Types
+
+| Type Module | Used By |
+|-------------|---------|
+| `auth.ts` | Server auth, client hooks |
+| `user.ts` | Server services, client routes |
+| `account.ts` | Server services, client routes |
+| `api.ts` | Server routes, client API calls |
+
+---
+
+## External Dependencies [HIGH]
+
+### NPM Packages
+
+#### Backend
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `hono` | 4.11.x | Web framework |
+| `@hono/zod-openapi` | 1.2.x | OpenAPI integration |
+| `@hono/swagger-ui` | 0.5.x | API documentation |
+| `zod` | 4.3.x | Schema validation |
+| `uuidv7` | 1.1.x | UUID generation |
+
+#### Frontend
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `react` | 19.x | UI library |
+| `@tanstack/react-router` | 1.144.x | File-based routing |
+| `@tanstack/react-query` | 5.90.x | Data fetching |
+| `react-hook-form` | 7.70.x | Form handling |
+| `tailwindcss` | 4.1.x | Styling |
+| `@radix-ui/*` | 1.x | UI primitives |
+| `lucide-react` | 0.562.x | Icons |
+| `sonner` | 2.0.x | Toast notifications |
+
+### Cloudflare Services
+
+| Service | Binding | Purpose |
+|---------|---------|---------|
+| D1 | `DB` | SQLite database |
+| KV | `SESSIONS` | Session storage |
+| R2 | `R2_BUCKET` | File storage |
+
+### External APIs
+
+| Service | Protocol | Purpose |
+|---------|----------|---------|
+| Google OAuth | OAuth 2.0 | Authentication |
+| SendGrid | REST API | Email delivery |
+
+---
+
+## Dependency Rules
+
+### Allowed Dependencies
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                        Routes                            │
+│    ┌─────────────────────────────────────────────────┐  │
+│    │                   Services                       │  │
+│    │    ┌─────────────────────────────────────────┐  │  │
+│    │    │                Auth/Lib                  │  │  │
+│    │    │    ┌─────────────────────────────────┐  │  │  │
+│    │    │    │              DB                  │  │  │  │
+│    │    │    └─────────────────────────────────┘  │  │  │
+│    │    └─────────────────────────────────────────┘  │  │
+│    └─────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Rules**:
+1. Routes → Services → DB (never skip layers)
+2. Middleware can access Auth and Lib
+3. Services can access DB and Lib
+4. Auth can access DB for role lookups
+5. Shared schemas/types accessible by all layers
+
+### Forbidden Dependencies
+
+| Layer | Cannot Import |
+|-------|---------------|
+| DB | Services, Routes, Middleware |
+| Lib | Services, Routes |
+| Auth | Services, Routes |
+| Services | Routes, Middleware |
+| Shared | Any server/client specific code |
+
+---
+
+## Import Aliases
+
+| Alias | Maps To | Usage |
+|-------|---------|-------|
+| `@/*` | `src/client/*` | Client-only imports |
+| `@server/*` | `src/server/*` | Server-only imports |
+| `@shared/*` | `src/shared/*` | Shared imports |
+
+**Example**:
+```typescript
+// In client code
+import { Button } from '@/components/ui/button'
+import { userSchema } from '@shared/schemas/user'
+
+// In server code
+import { UsersService } from '@server/services/users'
+import { userSchema } from '@shared/schemas/user'
+```
+
+---
+
+## Circular Dependency Prevention
+
+The architecture prevents circular dependencies through:
+
+1. **Layered architecture**: Lower layers cannot import higher layers
+2. **Shared types**: Common types in `shared/` break potential cycles
+3. **Dependency injection**: Services receive dependencies via constructor
+4. **Interface segregation**: Guards expose minimal interfaces
+
+**Build-time checks**: TypeScript's `noImplicitAny` and path aliases enforce boundaries.

package/templates/base/docs/architecture/drizzle-migration-plan.md

@@ -0,0 +1,125 @@
+# Mapeamento do Drizzle e plano de migracao para SQL puro
+
+> Status: Drizzle removido (PDB-823, Jan 2026). Este documento permanece como historico do plano.
+
+Contexto canonico: `docs/app_spec.txt`.
+
+## Objetivo
+
+Documentar onde o Drizzle e utilizado hoje e propor uma sequencia de migracao para SQL puro (D1/SQLite) com menor risco.
+
+## Inventario de uso do Drizzle
+
+### Tooling e configuracao
+
+- `config/drizzle.config.ts`
+- `package.json` (scripts `db:push`, `db:generate`, `db:studio`; dependencias `drizzle-orm`, `drizzle-kit`)
+- `packages/bhono-app/templates/base/config/drizzle.config.ts`
+- `packages/bhono-app/templates/base/package.json` (mesmos scripts/dependencias)
+
+### Schema e helpers
+
+- `src/server/db/schema/index.ts`
+- `src/server/db/schema/*.ts` (users, accounts, user-accounts, invitations, refresh-tokens, audit-logs)
+- `src/server/lib/schema-helpers.ts`
+- `packages/bhono-app/templates/base/src/server/db/schema/*`
+- `packages/bhono-app/templates/base/src/server/lib/schema-helpers.ts`
+
+### Client e cross-cutting
+
+- `src/server/db/client.ts` (createDb com `drizzle-orm/d1`)
+- `src/server/lib/transaction.ts` (types baseados em `Database['transaction']`)
+- `src/server/lib/audited-db.ts` (Table/SQL do Drizzle, `.returning()`)
+- `src/server/lib/audit.ts` (grava em `audit_logs` usando `db.insert`)
+- `packages/bhono-app/templates/base/src/server/db/client.ts`
+- `packages/bhono-app/templates/base/src/server/lib/transaction.ts`
+- `packages/bhono-app/templates/base/src/server/lib/audited-db.ts`
+- `packages/bhono-app/templates/base/src/server/lib/audit.ts`
+
+### Services (queries principais)
+
+- `src/server/services/auth.ts` (insert/update/returning, tokens, refresh)
+- `src/server/services/users.ts` (filtros, subquery IN, soft delete, paginacao)
+- `src/server/services/accounts.ts` (filtros, subquery IN, soft delete, paginacao)
+- `src/server/services/invitations.ts` (joins, expiracao, create/accept)
+- `src/server/services/audits.ts` (filtros, paginacao)
+- `packages/bhono-app/templates/base/src/server/services/*` (espelho)
+
+### Middleware e rotas
+
+- `src/server/middleware/auth.ts` (select por id + soft delete)
+- `src/server/middleware/account.ts` (select por membership)
+- `src/server/routes/health/handlers.ts` (db.run com `sql` do Drizzle)
+- `src/server/routes/auth/test-login.ts` (select simples)
+- `packages/bhono-app/templates/base/src/server/middleware/*`
+- `packages/bhono-app/templates/base/src/server/routes/*`
+
+### Testes
+
+- `tests/integration/setup.ts` (drizzle + better-sqlite3, schema SQL inline)
+- `packages/bhono-app/templates/base/tests/integration/*` (espelho com drizzle)
+- `packages/bhono-app/templates/base/tests/integration/security/*.test.ts` (comentarios e wrappers de drizzle)
+
+## Padroes de query usados hoje
+
+- Select simples por id + soft delete (`deleted_at IS NULL`).
+- Select com join (`invitations` + `users`/`accounts`).
+- Subquery com `IN` (multi-tenancy em users/accounts).
+- Paginacao com `LIMIT/OFFSET` + `count(*)`.
+- `LIKE` para filtros por nome/email/dominio.
+- Inserts/updates com `returning()`.
+- Soft delete (update de `deleted_at` e audit).
+- Transacoes (create user + account + membership; depende de `db.transaction`).
+- Uso pontual de SQL raw (`sql\`SELECT 1\`` na healthcheck).
+
+## Sequencia recomendada de migracao
+
+1) Padroes e convencoes de SQL puro (PDB-813)
+- Definir placeholders, naming, soft delete, mapeamento/validacao, tratamento de erros.
+
+2) Helper SQL para D1 (PDB-814)
+- API de execucao (queryOne/queryAll/exec), bind de parametros e typing.
+- Confirmar comportamento de transacoes no D1 (ex.: `batch`) antes de migrar flows criticos.
+
+3) Camadas cross-cutting (PDB-815)
+- Reimplementar `audited-db` e `audit` com SQL puro.
+- Ajustar `transaction.ts` para o novo helper.
+
+4) Modulos de negocio (PDB-816 a PDB-821)
+- Auth -> Users -> Accounts -> Invitations -> Audits -> Middleware.
+- Sempre migrar junto com testes afetados.
+
+5) Estrategia sem migrations (PDB-822)
+- Consolidar `schema.sql` versionado e bootstrap/reset com `wrangler d1 execute`.
+- Alinhar `tests/integration/setup.ts` com `schema.sql`.
+
+6) Remocao de Drizzle (PDB-823)
+- Limpar dependencias, scripts e tipos remanescentes.
+
+## Riscos e mitigacoes
+
+- Consistencia multi-tenant: garantir `account_id` em todas as queries.
+  - Mitigacao: helper com scoping obrigatorio e testes de autorizacao.
+
+- Perda de audit trail: `audited-*` depende de `returning()`.
+  - Mitigacao: selecionar estado anterior antes do update e usar `RETURNING` quando suportado.
+
+- SQL injection: migracao aumenta risco manual.
+  - Mitigacao: prepared statements, helpers obrigatorios e proibicao de string interpolation.
+
+- Diferencas de comportamento entre D1 e sqlite local.
+  - Mitigacao: alinhar `schema.sql` e tests com D1 (usar `wrangler d1` para smoke tests).
+
+- Quebra de testes e mocks.
+  - Mitigacao: atualizar `tests/integration/setup.ts` e mocks ao mesmo tempo que cada modulo.
+
+## Entregaveis desta etapa (PDB-812)
+
+- Inventario de arquivos e padroes de query.
+- Sequencia recomendada e dependencias entre modulos.
+- Riscos e mitigacoes para orientar as proximas issues.
+
+## Notas
+
+- Tudo que for alterado no `src/` deve ser espelhado em `packages/bhono-app/templates/base/`.
+- O seed ja gera SQL puro; pode ser mantido e ajustado conforme o `schema.sql`.

package/templates/base/docs/architecture/erd.md

@@ -1,7 +1,7 @@
 # ERD - Hono Boilerplate (D1/SQLite)
 
 ## Visao geral
-Este documento descreve o modelo relacional atual utilizado no banco D1 (SQLite) do projeto. Ele foi derivado diretamente dos schemas em `src/server/db/schema`.
+Este documento descreve o modelo relacional atual utilizado no banco D1 (SQLite) do projeto. Ele foi derivado diretamente de `schema.sql`.
 
 ## Diagrama (Mermaid)
 ```mermaid

package/templates/base/docs/architecture/sql-standards.md

@@ -0,0 +1,100 @@
+# Padrao de SQL puro e mapeamento de resultados
+
+Contexto canonico: `docs/app_spec.txt`.
+
+## Objetivo
+
+Definir convencoes para SQL puro no D1/SQLite, incluindo bind de parametros,
+mapa de resultados e tratamento de erros para manter consistencia e seguranca.
+
+## Escopo
+
+- SQL usado no backend (services, middleware, lib).
+- Mapeamento de resultados para tipos de dominio.
+- Soft delete, multi-tenancy, auditoria e paginacao.
+
+## Convencoes de SQL
+
+### Estilo
+
+- Keywords em UPPERCASE (SELECT, FROM, WHERE).
+- Tabelas e colunas em snake_case (como no schema atual).
+- Evitar `SELECT *`: listar colunas para mapear explicitamente.
+- Preferir alias curtos (`users u`, `accounts a`) quando houver join.
+
+### Parametros e seguranca
+
+- Nunca interpolar strings diretamente em SQL.
+- Usar placeholders posicionais `?` com `stmt.bind(...)`.
+- Proibir concatenacao de SQL com valores de usuario.
+
+### Soft delete
+
+- Queries de leitura devem sempre filtrar `deleted_at IS NULL` quando aplicavel.
+- Remocoes devem ser soft delete (update de `deleted_at`, `deleted_by_id`, `updated_at`).
+- Restauracao deve limpar `deleted_at` e `deleted_by_id`.
+
+### Multi-tenancy
+
+- Toda query de dados multi-tenant deve filtrar `account_id`.
+- Para super-admin, permitir bypass explicito em query (flag de contexto).
+
+### Paginacao e filtros
+
+- Paginacao via `LIMIT`/`OFFSET`.
+- Contagem total via `SELECT count(*)`.
+- Filtros textuais com `LIKE` e `%`.
+
+### Datas e tipos
+
+- Datas em TEXT ISO (ex.: `created_at`) ou INTEGER unix (ex.: `refresh_tokens`).
+- Mapear `INTEGER` para boolean quando necessario (0/1).
+- Campos JSON em TEXT devem ser parseados ao ler.
+
+## Mapeamento de resultados
+
+### Regra geral
+
+- Toda query deve ter um mapper explicito (funcao ou schema) que:
+  - valida shape (preferencialmente com Zod),
+  - converte tipos (INTEGER -> boolean, TEXT JSON -> objeto),
+  - normaliza campos opcionais.
+
+### Exemplo (conceitual)
+
+- Query retorna `is_super_admin` (INTEGER).
+- Mapper converte para boolean e retorna `isSuperAdmin`.
+- Campo `provider_ids` (TEXT JSON) vira `string[]`.
+
+## Erros e tratamento
+
+- `NotFoundError` quando `SELECT` nao retorna registros esperados.
+- `ConflictError` quando violar unicidade (dominio/email/token).
+- `ForbiddenError` para acesso indevido a `account_id`.
+- Propagar erro de SQL com mensagem generica (evitar leak de detalhes).
+
+## Transacoes
+
+- D1 nao oferece transacoes nativas. Operacoes multi-step devem ser planejadas
+  para serem idempotentes ou dividir em `batch` quando possivel.
+- Para fluxos criticos, validar resultados intermediarios e registrar auditoria
+  com `transaction_id` compartilhado.
+
+## Auditoria
+
+- Toda mutacao relevante deve registrar `audit_logs`.
+- Usar `transaction_id` comum para agrupar operacoes.
+- Registrar `changes` apenas com campos relevantes.
+
+## Checklist de migracao por modulo
+
+- Listar queries atuais.
+- Reescrever SQL com bind e filtros `account_id`/`deleted_at`.
+- Adicionar mapper/validator.
+- Atualizar testes afetados.
+
+## Referencias
+
+- `docs/architecture/erd.md`
+- `docs/architecture/data-requirements.md`
+- `docs/architecture/drizzle-migration-plan.md`