@qazuor/claude-code-config 0.1.0

package/templates/docs/templates/tech-analysis-template.md

@@ -0,0 +1,800 @@
+# Technical Analysis
+
+## {Feature Name}
+
+**Date**: YYYY-MM-DD
+**Related PDR**: [PDR.md](./PDR.md)
+**Status**: Draft | In Review | Approved | Implemented
+**Tech Lead**: {Name}
+
+---
+
+## 1. Executive Summary
+
+**Feature Overview:**
+{1-2 paragraph summary of what we're building}
+
+**Technical Approach:**
+{High-level summary of the technical solution}
+
+**Key Decisions:**
+
+1. {Decision 1}
+2. {Decision 2}
+3. {Decision 3}
+
+**Estimated Complexity**: Low | Medium | High | Very High
+
+**Estimated Timeline**: {X} days/weeks
+
+---
+
+## 2. Architecture Overview
+
+### 2.1 System Architecture
+
+```mermaid
+graph TB
+    Client[Client Apps]
+    API[API Layer]
+    Service[Service Layer]
+    DB[(Database)]
+
+    Client -->|HTTP/REST| API
+    API -->|Business Logic| Service
+    Service -->|Drizzle ORM| DB
+
+    subgraph "Apps"
+        Web[Web - Astro]
+        Admin[Admin - TanStack Start]
+    end
+
+    subgraph "Backend"
+        Hono[Hono Routes]
+        Services[Services]
+        Models[Models]
+    end
+
+    Client --> Web
+    Client --> Admin
+    API --> Hono
+    Service --> Services
+    Service --> Models
+```text
+
+**Description:**
+{Explain the architecture and how components interact}
+
+### 2.2 Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Frontend
+    participant API
+    participant Service
+    participant Database
+
+    User->>Frontend: Action
+    Frontend->>API: HTTP Request
+    API->>Service: Business Logic
+    Service->>Database: Query
+    Database-->>Service: Result
+    Service-->>API: Response
+    API-->>Frontend: JSON
+    Frontend-->>User: UI Update
+```text
+
+**Flow Description:**
+{Explain the data flow step by step}
+
+---
+
+## 3. Technical Stack
+
+### 3.1 Technologies Used
+
+| Layer | Technology | Version | Why Chosen |
+|-------|-----------|---------|------------|
+| Frontend (Web) | Astro | {version} | {reason} |
+| Frontend (Admin) | TanStack Start | {version} | {reason} |
+| UI Components | React 19 | {version} | {reason} |
+| Styling | Tailwind + Shadcn | {version} | {reason} |
+| Backend | Hono | {version} | {reason} |
+| Database | PostgreSQL | {version} | {reason} |
+| ORM | Drizzle | {version} | {reason} |
+| Validation | Zod | {version} | {reason} |
+
+### 3.2 New Dependencies
+
+**Packages to Add:**
+
+```json
+{
+  "dependencies": {
+    "{package-name}": "{version}"
+  },
+  "devDependencies": {
+    "{package-name}": "{version}"
+  }
+}
+```text
+
+**Justification:**
+
+- **{package-name}**: {Why needed, alternatives considered, bundle size impact}
+
+**Bundle Impact:**
+
+- Current size: {X} KB
+- After additions: {Y} KB
+- Increase: {Z} KB ({percentage}%)
+
+---
+
+## 4. Database Design
+
+### 4.1 Schema Changes
+
+#### New Tables
+
+```typescript
+// packages/db/src/schemas/{entity}/{entity}.schema.ts
+
+export const {tableName} = pgTable("{table_name}", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  {field1}: varchar("{field1}", { length: 255 }).notNull(),
+  {field2}: integer("{field2}").notNull(),
+  {field3}: text("{field3}"),
+
+  // Relationships
+  {foreignKey}: uuid("{foreign_key}").references(() => {otherTable}.id),
+
+  // Audit fields
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  deletedAt: timestamp("deleted_at"),
+});
+```text
+
+#### Modified Tables
+
+**Table**: {table_name}
+
+- **Add columns**: {column1}, {column2}
+- **Modify columns**: {column} - {old type} → {new type}
+- **Remove columns**: {column} (reason: {why})
+
+### 4.2 Relationships
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : has
+    ENTITY_B }o--|| ENTITY_C : belongs_to
+
+    ENTITY_A {
+        uuid id PK
+        string field1
+        timestamp created_at
+    }
+
+    ENTITY_B {
+        uuid id PK
+        uuid entity_a_id FK
+        uuid entity_c_id FK
+    }
+
+    ENTITY_C {
+        uuid id PK
+        string name
+    }
+```text
+
+**Relationship Details:**
+
+- {Entity A} → {Entity B}: {Type of relationship and why}
+- {Entity B} → {Entity C}: {Type of relationship and why}
+
+### 4.3 Indexes
+
+**New Indexes:**
+
+```sql
+CREATE INDEX idx_{table}_{column} ON {table}({column});
+CREATE INDEX idx_{table}_{col1}_{col2} ON {table}({col1}, {col2});
+```text
+
+**Justification:**
+
+- **idx_{table}_{column}**: {Query pattern that benefits, expected improvement}
+
+### 4.4 Migrations
+
+**Migration Strategy:**
+
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+**Rollback Plan:**
+
+- {How to rollback if needed}
+
+**Data Migration:**
+
+- Existing data: {How to migrate/transform}
+- Default values: {For new fields}
+
+---
+
+## 5. API Design
+
+### 5.1 Endpoints
+
+#### Endpoint 1: Create {Entity}
+
+```text
+POST /api/{entities}
+```text
+
+**Request:**
+
+```typescript
+{
+  field1: string;
+  field2: number;
+  field3?: string;
+}
+```text
+
+**Response:**
+
+```typescript
+{
+  success: true;
+  data: {
+    id: string;
+    field1: string;
+    field2: number;
+    createdAt: string;
+  }
+}
+```text
+
+**Authentication**: Required | Public
+**Authorization**: {Roles/permissions}
+**Rate Limit**: {X} requests per minute
+
+---
+
+#### Endpoint 2: Get {Entity}
+
+```text
+GET /api/{entities}/:id
+```text
+
+**Response:**
+
+```typescript
+{
+  success: true;
+  data: {
+    id: string;
+    field1: string;
+    field2: number;
+    // ... all fields
+  }
+}
+```text
+
+---
+
+#### Endpoint 3: List {Entities}
+
+```text
+GET /api/{entities}?page=1&pageSize=20&orderBy=createdAt&order=desc
+```text
+
+**Query Parameters:**
+
+- `page`: number (default: 1)
+- `pageSize`: number (default: 20, max: 100)
+- `orderBy`: string (default: "createdAt")
+- `order`: "asc" | "desc" (default: "desc")
+- `q`: string (search query)
+
+**Response:**
+
+```typescript
+{
+  success: true;
+  data: {
+    items: Entity[];
+    pagination: {
+      page: number;
+      pageSize: number;
+      total: number;
+      totalPages: number;
+    }
+  }
+}
+```text
+
+---
+
+### 5.2 Error Handling
+
+**Error Response Format:**
+
+```typescript
+{
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    details?: any;
+  }
+}
+```text
+
+**Error Codes:**
+
+- `VALIDATION_ERROR` (400): Input validation failed
+- `UNAUTHORIZED` (401): Not authenticated
+- `FORBIDDEN` (403): Not authorized
+- `NOT_FOUND` (404): Resource not found
+- `CONFLICT` (409): Resource already exists
+- `INTERNAL_ERROR` (500): Server error
+
+---
+
+## 6. Service Layer Design
+
+### 6.1 Service Structure
+
+```typescript
+// packages/service-core/src/services/{entity}/{entity}.service.ts
+
+export class {Entity}Service extends BaseCrudService<
+  {Entity},
+  {Entity}Model,
+  Create{Entity}Schema,
+  Update{Entity}Schema,
+  Search{Entity}Schema
+> {
+  constructor(ctx: ServiceContext, model?: {Entity}Model) {
+    super(ctx, model ?? new {Entity}Model(ctx.db));
+  }
+
+  // Custom methods
+  async customMethod({ input }: { input: CustomInput }): Promise<CustomOutput> {
+    return this.runWithLoggingAndValidation(
+      "customMethod",
+      { input },
+      async () => {
+        // Implementation
+      }
+    );
+  }
+}
+```text
+
+### 6.2 Business Logic
+
+**Validation Rules:**
+
+1. {Rule 1}
+2. {Rule 2}
+3. {Rule 3}
+
+**Business Rules:**
+
+1. {Rule 1 and implementation}
+2. {Rule 2 and implementation}
+
+**Transactions:**
+
+- {Operation 1}: Requires transaction because {reason}
+- {Operation 2}: Requires transaction because {reason}
+
+---
+
+## 7. Frontend Implementation
+
+### 7.1 Components Structure
+
+```text
+apps/web/src/components/{feature}/
+├── {Feature}List.tsx
+├── {Feature}Card.tsx
+├── {Feature}Form.tsx
+└── {Feature}Detail.tsx
+```text
+
+**Components:**
+
+#### {Feature}List
+
+- **Purpose**: {What it does}
+- **Props**: {List props}
+- **State**: {What state it manages}
+- **Queries**: {TanStack Query hooks used}
+
+#### {Feature}Form
+
+- **Purpose**: {What it does}
+- **Props**: {List props}
+- **Validation**: Client-side with Zod
+- **Submit**: {How it submits}
+
+### 7.2 State Management
+
+**TanStack Query:**
+
+```typescript
+// Query keys
+const queryKeys = {
+  all: ['{entity}'] as const,
+  lists: () => [...queryKeys.all, 'list'] as const,
+  list: (filters: Filters) => [...queryKeys.lists(), filters] as const,
+  details: () => [...queryKeys.all, 'detail'] as const,
+  detail: (id: string) => [...queryKeys.details(), id] as const,
+};
+
+// Queries
+const use{Entity}Query = (id: string) => {
+  return useQuery({
+    queryKey: queryKeys.detail(id),
+    queryFn: () => fetch{Entity}(id),
+  });
+};
+
+// Mutations
+const useCreate{Entity}Mutation = () => {
+  return useMutation({
+    mutationFn: create{Entity},
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.lists() });
+    },
+  });
+};
+```text
+
+### 7.3 Routing
+
+**Web App (Astro):**
+
+```text
+apps/web/src/pages/
+└── {feature}/
+    ├── index.astro         # List view
+    ├── [id].astro          # Detail view
+    └── new.astro           # Create view
+```text
+
+**Admin App (TanStack Start):**
+
+```typescript
+// apps/admin/src/routes/{feature}/
+export const Route = createFileRoute('/{feature}/')({
+  component: {Feature}List,
+  loader: async () => {
+    // Preload data
+  },
+});
+```text
+
+---
+
+## 8. Integration Points
+
+### 8.1 Internal Integrations
+
+**Package Dependencies:**
+
+- `@repo/schemas` - Validation schemas
+- `@repo/db` - Database models
+- `@repo/service-core` - Business logic
+- `@repo/utils` - Utility functions
+
+**Service Dependencies:**
+
+- {Service 1}: {Why needed, how used}
+- {Service 2}: {Why needed, how used}
+
+### 8.2 External Integrations
+
+**Third-Party Services:**
+
+#### {Service Name}
+
+- **Purpose**: {Why we use it}
+- **Integration point**: {Where in our code}
+- **Error handling**: {How we handle failures}
+- **Fallback**: {What happens if unavailable}
+
+---
+
+## 9. Security Considerations
+
+### 9.1 Authentication & Authorization
+
+**Authentication:**
+
+- Provider: Clerk
+- Flow: {Auth flow description}
+- Token handling: {How tokens are managed}
+
+**Authorization:**
+
+- Role-based: Yes
+- Roles required: {List roles}
+- Permissions: {List permissions}
+- Permission checks: {Where and how}
+
+### 9.2 Input Validation
+
+**Client-Side:**
+
+- Zod schemas
+- Real-time validation
+- User-friendly error messages
+
+**Server-Side:**
+
+- Zod validation with `zValidator` middleware
+- SQL injection prevention (Drizzle parameterized queries)
+- XSS prevention (input sanitization)
+
+### 9.3 Data Protection
+
+**Sensitive Data:**
+
+- {Type of sensitive data}
+- Encryption: {At rest | In transit}
+- Access control: {Who can access}
+
+**PII Handling:**
+
+- {How PII is collected}
+- {How PII is stored}
+- {How PII is accessed}
+- {Retention policy}
+
+---
+
+## 10. Performance Considerations
+
+### 10.1 Database Optimization
+
+**Query Optimization:**
+
+- Indexes: {List indexes and rationale}
+- Query patterns: {Common queries and optimization}
+- Pagination: Cursor-based | Offset-based
+
+**Expected Load:**
+
+- Reads per second: {X}
+- Writes per second: {Y}
+- Concurrent users: {Z}
+
+### 10.2 API Performance
+
+**Caching Strategy:**
+
+- Cache what: {What to cache}
+- Cache where: {Client | CDN | Server}
+- TTL: {Time to live}
+- Invalidation: {When to invalidate}
+
+**Rate Limiting:**
+
+- Limit: {X} requests per {time}
+- Strategy: {Per user | Per IP | Global}
+
+### 10.3 Frontend Performance
+
+**Bundle Size:**
+
+- Component size: {X} KB
+- Dependencies: {Y} KB
+- Total impact: {Z} KB
+
+**Loading Strategy:**
+
+- Critical path: {What loads first}
+- Lazy loading: {What loads on demand}
+- Code splitting: {How code is split}
+
+**Rendering:**
+
+- SSR: {What is server-rendered}
+- Client hydration: {What hydrates}
+- Islands: {What uses islands architecture}
+
+---
+
+## 11. Testing Strategy
+
+### 11.1 Test Coverage
+
+**Unit Tests (90%+ coverage):**
+
+- Models: {Test scenarios}
+- Services: {Test scenarios}
+- Utilities: {Test scenarios}
+
+**Integration Tests:**
+
+- API endpoints: {Test scenarios}
+- Service integration: {Test scenarios}
+
+**E2E Tests:**
+
+- User flow 1: {Scenario}
+- User flow 2: {Scenario}
+
+### 11.2 Test Data
+
+**Fixtures:**
+
+- {Fixture 1}: {Purpose}
+- {Fixture 2}: {Purpose}
+
+**Mocks:**
+
+- {Mock 1}: {What's mocked and why}
+- {Mock 2}: {What's mocked and why}
+
+---
+
+## 12. Deployment Strategy
+
+### 12.1 Deployment Plan
+
+**Deployment Type**: {Big Bang | Phased | Feature Flag | Canary}
+
+**Steps:**
+
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+**Environment Variables:**
+
+```bash
+
+# New variables to add
+
+{VAR_NAME}={description}
+{VAR_NAME_2}={description}
+```text
+
+### 12.2 Database Migration
+
+**Migration Script:**
+
+```bash
+
+# Run migration
+
+pnpm db:migrate
+```text
+
+**Verification:**
+
+1. {Verification step 1}
+2. {Verification step 2}
+
+**Rollback:**
+
+```sql
+-- Rollback script if needed
+{rollback SQL}
+```text
+
+### 12.3 Monitoring
+
+**Metrics to Monitor:**
+
+- API response time: {endpoint} < {X}ms
+- Database query time: < {Y}ms
+- Error rate: < {Z}%
+- User actions: {specific actions to track}
+
+**Alerts:**
+
+- {Metric} > {threshold}: {Action to take}
+- {Error type}: {Action to take}
+
+---
+
+## 13. Technical Risks
+
+### Risk 1: {Risk Name}
+
+**Probability**: High | Medium | Low
+**Impact**: High | Medium | Low
+
+**Description:**
+{What could go wrong}
+
+**Mitigation:**
+{How we'll prevent or handle it}
+
+**Contingency:**
+{Backup plan if it happens}
+
+---
+
+### Risk 2: {Risk Name}
+
+{Continue with additional risks}
+
+---
+
+## 14. Technical Debt
+
+**Known Debt:**
+
+1. {Debt item 1} - {Plan to address} - {When}
+2. {Debt item 2} - {Plan to address} - {When}
+
+**Acceptable Tradeoffs:**
+
+- {Tradeoff 1}: {Why acceptable}
+- {Tradeoff 2}: {Why acceptable}
+
+---
+
+## 15. Open Questions
+
+**Q1**: {Technical question}
+**Status**: Open | Resolved
+**Resolution**: {Answer if resolved}
+
+**Q2**: {Technical question}
+**Status**: Open | Resolved
+**Resolution**: {Answer if resolved}
+
+---
+
+## 16. Implementation Checklist
+
+- [ ] Database schema designed
+- [ ] Zod schemas created
+- [ ] Drizzle models implemented
+- [ ] Services implemented
+- [ ] API routes created
+- [ ] Frontend components built
+- [ ] Tests written (90%+ coverage)
+- [ ] Documentation updated
+- [ ] Security review passed
+- [ ] Performance review passed
+- [ ] Deployment plan ready
+
+---
+
+## 17. Related Documents
+
+- [PDR (Product Design Requirements)](./PDR.md)
+- [TODOs & Task Breakdown](./TODOs.md)
+- [Code Review Report](./code-review.md) *(after implementation)*
+
+---
+
+## 18. Changelog
+
+| Date | Author | Changes | Version |
+|------|--------|---------|---------|
+| YYYY-MM-DD | {Name} | Initial draft | 0.1 |
+| YYYY-MM-DD | {Name} | Added architecture diagrams | 0.2 |
+| YYYY-MM-DD | {Name} | Finalized technical approach | 1.0 |
+
+---
+
+**Status**: {Draft | In Review | Approved | Implemented}
+**Next Steps**: {What happens next}
+**Owner**: {Who is responsible}
+