specpulse 1.4.1__py3-none-any.whl → 1.4.2__py3-none-any.whl

specpulse/resources/templates/decomposition/integration-plan.md

@@ -1,135 +1,287 @@
-# Integration Plan: {{ feature_name }}
+# Integration Plan: {{feature_name}}
 
-## Metadata
-- **Spec ID**: {{ spec_id }}
-- **Decomposition Date**: {{ decomposition_date }}
-- **Services Count**: {{ service_count }}
-- **Generated**: {{ date }}
-- **Version**: {{ version }}
+## Overview
+Integration strategy for microservices implementing {{feature_name}}
 
-## Service Overview
-
-{{ service_list }}
-
-## Integration Architecture
+## Service Architecture
 
 ```mermaid
-{{ architecture_diagram }}
-```
+graph TD
+    CLIENT[Client Application]
+    GATEWAY[API Gateway]
 
-## Communication Strategy
+    AUTH[Auth Service]
+    USER[User Service]
+    NOTIFY[Notification Service]
 
-### Synchronous Communication
-{{ sync_communication }}
+    DB_AUTH[(Auth DB)]
+    DB_USER[(User DB)]
 
-### Asynchronous Communication
-{{ async_communication }}
+    CACHE[Redis Cache]
+    QUEUE[Message Queue]
 
-## Data Consistency Strategy
+    CLIENT --> GATEWAY
+    GATEWAY --> AUTH
+    GATEWAY --> USER
 
-### Transaction Boundaries
-{{ transaction_strategy }}
+    AUTH --> DB_AUTH
+    AUTH --> CACHE
+    AUTH --> QUEUE
 
-### Event Sourcing
-{{ event_sourcing }}
+    USER --> DB_USER
+    USER --> CACHE
+    USER --> QUEUE
 
-### Saga Patterns
-{{ saga_patterns }}
+    QUEUE --> NOTIFY
 
-## Integration Phases
+    AUTH -.->|Events| USER
+    USER -.->|Events| NOTIFY
+```
 
-### Phase 1: Service Infrastructure
-**Duration**: {{ phase1_duration }}
-**Deliverables**:
-- Service discovery setup
-- API Gateway configuration
-- Load balancer setup
-- Service mesh deployment
+## Service Communication Matrix
+
+| Source Service | Target Service | Protocol | Pattern | Purpose |
+|---------------|---------------|----------|---------|---------|
+| API Gateway | Auth Service | REST | Request-Response | Authentication |
+| API Gateway | User Service | REST | Request-Response | User operations |
+| Auth Service | User Service | Event | Pub-Sub | User created/updated |
+| User Service | Notification | Event | Pub-Sub | Send notifications |
+| All Services | Cache | Redis | Cache-Aside | Performance |
+
+## Integration Points
+
+### 1. Authentication Flow
+**Services**: API Gateway → Auth Service → User Service
+
+**Flow**:
+1. Client sends credentials to API Gateway
+2. Gateway forwards to Auth Service
+3. Auth Service validates and generates token
+4. Auth Service publishes `user.authenticated` event
+5. User Service updates last login timestamp
+6. Token returned to client
+
+**Contracts**:
+- REST API: `POST /auth/login`
+- Event: `user.authenticated`
+- Response: JWT token
+
+### 2. User Registration Flow
+**Services**: API Gateway → User Service → Auth Service → Notification Service
+
+**Flow**:
+1. Client sends registration data to API Gateway
+2. Gateway forwards to User Service
+3. User Service creates user record
+4. User Service publishes `user.created` event
+5. Auth Service creates authentication record
+6. Notification Service sends welcome email
+7. Confirmation sent to client
+
+**Contracts**:
+- REST API: `POST /users/register`
+- Events: `user.created`, `auth.created`, `notification.sent`
+
+### 3. Data Synchronization
+**Services**: All services with shared data
+
+**Strategy**:
+- Event-driven synchronization
+- Eventual consistency model
+- Compensation for failures
+
+**Events**:
+- `user.updated` - Profile changes
+- `auth.revoked` - Token invalidation
+- `permission.changed` - Authorization updates
 
-### Phase 2: Inter-Service Communication
-**Duration**: {{ phase2_duration }}
-**Deliverables**:
-- REST API endpoints
-- Message queue setup
-- Event bus configuration
-- Circuit breakers
+## API Gateway Configuration
 
-### Phase 3: Data Synchronization
-**Duration**: {{ phase3_duration }}
-**Deliverables**:
-- Data replication strategy
-- Cache synchronization
-- Event replay mechanisms
-- Consistency validation
+### Routing Rules
+```yaml
+routes:
+  - path: /api/v1/auth/*
+    service: auth-service
+    methods: [GET, POST, PUT, DELETE]
+
+  - path: /api/v1/users/*
+    service: user-service
+    methods: [GET, POST, PUT, DELETE]
+
+  - path: /api/v1/notifications/*
+    service: notification-service
+    methods: [GET, POST]
+```
 
-### Phase 4: Integration Testing
-**Duration**: {{ phase4_duration }}
-**Deliverables**:
-- Contract tests
-- End-to-end scenarios
-- Performance benchmarks
-- Chaos engineering tests
+### Security Policies
+- Rate limiting: 100 requests/minute per IP
+- Authentication: JWT validation
+- CORS: Configured for allowed origins
+- Request/Response validation
 
-## Service Dependencies
+## Message Queue Configuration
 
+### Exchanges and Queues
 ```yaml
-dependencies:
-  {{ service_dependencies }}
+exchanges:
+  - name: user-events
+    type: topic
+    durable: true
+
+  - name: auth-events
+    type: topic
+    durable: true
+
+queues:
+  - name: user-service-queue
+    bindings:
+      - exchange: auth-events
+        routing_key: auth.*
+
+  - name: notification-queue
+    bindings:
+      - exchange: user-events
+        routing_key: user.*
 ```
 
-## API Gateway Configuration
-
-### Routing Rules
-{{ routing_rules }}
+### Event Schema
+```json
+{
+  "eventId": "uuid",
+  "eventType": "user.created",
+  "timestamp": "ISO-8601",
+  "correlationId": "uuid",
+  "data": {
+    "userId": "uuid",
+    "email": "string"
+  }
+}
+```
 
-### Rate Limiting
-{{ rate_limiting }}
+## Service Discovery
 
-### Authentication Flow
-{{ auth_flow }}
+### Registration
+- Each service registers on startup
+- Health checks every 30 seconds
+- Deregistration on shutdown
 
-## Monitoring & Observability
+### Discovery
+- Service-to-service calls use discovery
+- Client-side load balancing
+- Circuit breaker implementation
 
-### Distributed Tracing
-- Correlation ID propagation
-- Span collection strategy
-- Trace sampling rate
+## Error Handling Strategy
 
-### Health Checks
-{{ health_checks }}
+### Retry Logic
+- Exponential backoff: 1s, 2s, 4s, 8s
+- Max retries: 3
+- Dead letter queue for failures
 
-### SLA Targets
-{{ sla_targets }}
+### Circuit Breaker
+- Threshold: 50% failure rate
+- Window: 60 seconds
+- Half-open attempts: Every 30 seconds
 
-## Rollout Strategy
+### Compensation
+- Saga pattern for distributed transactions
+- Compensation events for rollback
+- Audit log for all operations
 
-### Service Deployment Order
-1. {{ deployment_order }}
+## Testing Strategy
 
-### Feature Flags
-{{ feature_flags }}
+### Integration Tests
+1. **Service-to-Service**: Mock external dependencies
+2. **End-to-End**: Full flow testing
+3. **Contract Tests**: API and event contracts
+4. **Chaos Testing**: Failure scenarios
 
-### Rollback Plan
-{{ rollback_plan }}
+### Test Scenarios
+- [ ] Happy path: Complete user registration
+- [ ] Service failure: Auth service down
+- [ ] Network partition: Queue unreachable
+- [ ] Data consistency: Concurrent updates
+- [ ] Performance: High load conditions
 
-## SDD Compliance
-- [ ] Specifications for each integration point (Principle 1: Specification First)
-- [ ] Phased integration approach (Principle 2: Incremental Planning)
-- [ ] Contract tests defined (Principle 6: Quality Assurance)
-- [ ] Architecture decisions documented (Principle 7: Architecture Documentation)
-- [ ] Stakeholder communication plan (Principle 9: Stakeholder Alignment)
+## Monitoring and Observability
 
-## Risk Assessment
-
-### Integration Risks
-{{ integration_risks }}
+### Distributed Tracing
+- Correlation IDs across all services
+- Request flow visualization
+- Performance bottleneck identification
+
+### Metrics
+- Request rate per service
+- Error rate per integration point
+- Message queue depth
+- Cache hit ratio
+
+### Alerting
+- Service unavailable > 1 minute
+- Error rate > 5%
+- Queue depth > 1000 messages
+- Response time > 500ms (p95)
+
+## Security Considerations
+
+### Service-to-Service Authentication
+- mTLS for internal communication
+- Service accounts with limited scope
+- Regular key rotation
+
+### Data Protection
+- Encryption in transit (TLS)
+- Encryption at rest (database)
+- PII masking in logs
+
+## Deployment Strategy
+
+### Order of Deployment
+1. Infrastructure (Database, Cache, Queue)
+2. Core services (Auth, User)
+3. Support services (Notification)
+4. API Gateway
+5. Monitoring and logging
 
-### Mitigation Strategies
-{{ mitigation_strategies }}
+### Rollback Plan
+- Blue-green deployment
+- Database migration rollback scripts
+- Event replay capability
+- Configuration rollback
+
+## Performance Optimization
+
+### Caching Strategy
+- User profiles: 5 minutes TTL
+- Authentication tokens: Until expiry
+- Permissions: 1 minute TTL
+
+### Database Optimization
+- Read replicas for queries
+- Connection pooling
+- Query optimization
+- Proper indexing
+
+### Async Processing
+- Non-critical operations queued
+- Batch processing where possible
+- Event debouncing
+
+## Timeline
+
+| Phase | Duration | Tasks |
+|-------|----------|-------|
+| Setup | 2 days | Infrastructure, service discovery |
+| Core Integration | 5 days | Auth + User services |
+| Extended Integration | 3 days | Notification, monitoring |
+| Testing | 3 days | Integration tests, load tests |
+| Optimization | 2 days | Performance tuning |
 
 ## Success Criteria
+
 - [ ] All services communicating successfully
-- [ ] Data consistency maintained
+- [ ] End-to-end flows working
 - [ ] Performance targets met
-- [ ] Zero message loss
-- [ ] Graceful degradation working
+- [ ] Monitoring in place
+- [ ] Security scans passed
+- [ ] Documentation complete
+- [ ] Team trained on operations

specpulse/resources/templates/decomposition/interface.ts

@@ -1,20 +1,251 @@
 /**
- * {{ interface_name }}
- * {{ interface_description }}
- * 
- * Bounded Context: {{ bounded_context }}
- * Service: {{ service_name }}
+ * {{service_name}} Service Interfaces
+ * Generated from SPEC-{{spec_id}}
  */
 
-export interface {{ interface_name }} {
-  {{ methods }}
+// ============================================================================
+// Domain Entities
+// ============================================================================
+
+export interface {{Entity}} {
+  id: string;
+  name: string;
+  description?: string;
+  status: {{Entity}}Status;
+  metadata?: Record<string, any>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export enum {{Entity}}Status {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+  PENDING = 'pending',
+  DELETED = 'deleted'
+}
+
+// ============================================================================
+// Request/Response DTOs
+// ============================================================================
+
+export interface Create{{Entity}}Request {
+  name: string;
+  description?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface Update{{Entity}}Request {
+  name?: string;
+  description?: string;
+  status?: {{Entity}}Status;
+  metadata?: Record<string, any>;
 }
 
-// Data Transfer Objects
-{{ dto_definitions }}
+export interface {{Entity}}Response {
+  data: {{Entity}};
+  meta?: ResponseMeta;
+}
+
+export interface {{Entity}}ListResponse {
+  data: {{Entity}}[];
+  meta: PaginationMeta;
+}
+
+// ============================================================================
+// Service Interface
+// ============================================================================
+
+export interface {{ServiceName}}Service {
+  // CRUD Operations
+  create(data: Create{{Entity}}Request): Promise<{{Entity}}>;
+  findById(id: string): Promise<{{Entity}} | null>;
+  findAll(params: QueryParams): Promise<{{Entity}}ListResponse>;
+  update(id: string, data: Update{{Entity}}Request): Promise<{{Entity}}>;
+  delete(id: string): Promise<boolean>;
+
+  // Business Operations
+  activate(id: string): Promise<{{Entity}}>;
+  deactivate(id: string): Promise<{{Entity}}>;
+  bulkUpdate(ids: string[], data: Update{{Entity}}Request): Promise<{{Entity}}[]>;
+
+  // Query Operations
+  findByName(name: string): Promise<{{Entity}} | null>;
+  findByStatus(status: {{Entity}}Status): Promise<{{Entity}}[]>;
+  search(query: SearchQuery): Promise<{{Entity}}[]>;
+}
+
+// ============================================================================
+// Repository Interface
+// ============================================================================
+
+export interface {{Entity}}Repository {
+  // Basic CRUD
+  save(entity: {{Entity}}): Promise<{{Entity}}>;
+  findById(id: string): Promise<{{Entity}} | null>;
+  findAll(options?: FindOptions): Promise<{{Entity}}[]>;
+  update(id: string, data: Partial<{{Entity}}>): Promise<{{Entity}} | null>;
+  delete(id: string): Promise<boolean>;
+
+  // Batch Operations
+  saveMany(entities: {{Entity}}[]): Promise<{{Entity}}[]>;
+  deleteMany(ids: string[]): Promise<number>;
+
+  // Query Methods
+  findOne(filter: FilterQuery): Promise<{{Entity}} | null>;
+  find(filter: FilterQuery, options?: FindOptions): Promise<{{Entity}}[]>;
+  count(filter?: FilterQuery): Promise<number>;
+  exists(filter: FilterQuery): Promise<boolean>;
+}
+
+// ============================================================================
+// Event Interfaces
+// ============================================================================
+
+export interface {{Entity}}Event {
+  eventId: string;
+  eventType: {{Entity}}EventType;
+  entityId: string;
+  timestamp: Date;
+  data: {{Entity}};
+  metadata?: EventMetadata;
+}
+
+export enum {{Entity}}EventType {
+  CREATED = '{{entity}}.created',
+  UPDATED = '{{entity}}.updated',
+  DELETED = '{{entity}}.deleted',
+  ACTIVATED = '{{entity}}.activated',
+  DEACTIVATED = '{{entity}}.deactivated'
+}
+
+export interface EventMetadata {
+  userId?: string;
+  correlationId?: string;
+  source?: string;
+  version?: string;
+}
+
+// ============================================================================
+// Error Interfaces
+// ============================================================================
+
+export class {{Entity}}Error extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number,
+    public details?: any
+  ) {
+    super(message);
+    this.name = '{{Entity}}Error';
+  }
+}
 
-// Event Contracts
-{{ event_contracts }}
+export class {{Entity}}NotFoundError extends {{Entity}}Error {
+  constructor(id: string) {
+    super(
+      `{{Entity}} with ID ${id} not found`,
+      'ENTITY_NOT_FOUND',
+      404
+    );
+  }
+}
+
+export class {{Entity}}ValidationError extends {{Entity}}Error {
+  constructor(message: string, details: any) {
+    super(message, 'VALIDATION_ERROR', 400, details);
+  }
+}
+
+// ============================================================================
+// Helper Types
+// ============================================================================
+
+export interface QueryParams {
+  page?: number;
+  limit?: number;
+  sort?: SortField;
+  order?: SortOrder;
+  filter?: FilterQuery;
+}
+
+export interface FilterQuery {
+  [field: string]: any;
+}
+
+export interface FindOptions {
+  skip?: number;
+  limit?: number;
+  sort?: SortOptions;
+  projection?: ProjectionOptions;
+}
+
+export interface SortOptions {
+  [field: string]: SortOrder;
+}
+
+export interface ProjectionOptions {
+  [field: string]: 0 | 1;
+}
+
+export type SortField = 'name' | 'status' | 'createdAt' | 'updatedAt';
+export type SortOrder = 'asc' | 'desc' | 1 | -1;
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+export interface ResponseMeta {
+  timestamp: Date;
+  version: string;
+  [key: string]: any;
+}
+
+export interface SearchQuery {
+  text?: string;
+  fields?: string[];
+  fuzzy?: boolean;
+  limit?: number;
+}
+
+// ============================================================================
+// Configuration Interface
+// ============================================================================
+
+export interface {{ServiceName}}Config {
+  serviceName: string;
+  port: number;
+  database: DatabaseConfig;
+  cache?: CacheConfig;
+  messaging?: MessagingConfig;
+  monitoring?: MonitoringConfig;
+}
+
+export interface DatabaseConfig {
+  url: string;
+  poolSize?: number;
+  timeout?: number;
+}
+
+export interface CacheConfig {
+  url: string;
+  ttl?: number;
+  prefix?: string;
+}
+
+export interface MessagingConfig {
+  url: string;
+  exchange?: string;
+  queue?: string;
+}
 
-// Domain Types
-{{ domain_types }}
+export interface MonitoringConfig {
+  enabled: boolean;
+  endpoint?: string;
+  interval?: number;
+}