@pixel613/spec 1.0.1

package/templates/architectures/clean/csharp-aspnet.md

@@ -0,0 +1,56 @@
+# Architecture: Clean Architecture (C# + ASP.NET Core)
+
+## Project Structure
+```
+src/
+├── Domain/
+│   ├── Entities/Order.cs
+│   ├── ValueObjects/Money.cs
+│   ├── Events/OrderCreatedEvent.cs
+│   ├── Errors/DomainException.cs
+│   └── Interfaces/IOrderRepository.cs
+├── Application/
+│   ├── UseCases/CreateOrder/
+│   │   ├── CreateOrderCommand.cs
+│   │   ├── CreateOrderHandler.cs
+│   │   └── CreateOrderValidator.cs
+│   ├── Common/
+│   │   └── Behaviors/ValidationBehavior.cs
+│   └── DependencyInjection.cs
+├── Infrastructure/
+│   ├── Persistence/
+│   │   ├── ApplicationDbContext.cs
+│   │   ├── Repositories/OrderRepository.cs
+│   │   └── Configurations/OrderConfiguration.cs
+│   ├── Services/
+│   │   └── PaymentGateway.cs
+│   └── DependencyInjection.cs
+└── WebApi/
+    ├── Controllers/OrderController.cs
+    ├── Middleware/ExceptionHandlerMiddleware.cs
+    ├── Filters/
+    └── Program.cs
+```
+
+## Dependency Rule
+- Domain → depends on nothing outside, pure C# classes
+- Application → depends only on Domain; uses MediatR for CQRS
+- Infrastructure → implements Domain interfaces, EF Core DbContext
+- WebApi → depends on Application; ASP.NET Controllers + minimal APIs
+
+## Conventions
+- MediatR for Command/Query handling
+- FluentValidation for input validation
+- EF Core with Fluent API configuration (no data annotations on Domain)
+- DI registration in each layer's DependencyInjection.cs
+
+## File Naming
+- PascalCase: CreateOrderCommand.cs
+- One class per file
+- Folder-per-feature in Application (e.g., UseCases/CreateOrder/)
+
+## Testing
+- Domain: pure unit tests (xUnit)
+- Application: mock repositories (NSubstitute/Moq)
+- Infrastructure: integration tests (WebApplicationFactory, TestContainers)
+- WebApi: E2E tests (WebApplicationFactory)

package/templates/architectures/clean/go-gin.md

@@ -0,0 +1,50 @@
+# Architecture: Clean Architecture (Go + Gin)
+
+## Directory Structure
+```
+internal/
+├── domain/
+│   ├── entity/order.go            # Entities, Value Objects
+│   └── event/order_created.go     # Domain Events
+├── usecase/
+│   ├── create_order.go            # Use Cases (one file per use case)
+│   └── interfaces.go              # Port interfaces
+├── infrastructure/
+│   ├── postgres/
+│   │   └── order_repo.go          # Repository implementation
+│   ├── redis/
+│   │   └── cache.go               # Cache implementation (if any)
+│   └── config/
+│       └── env.go                 # Environment configuration
+├── handler/
+│   └── http/
+│       ├── order_handler.go       # Gin handler
+│       ├── middleware/
+│       │   └── auth.go            # Middleware
+│       └── router.go              # Route definitions
+└── pkg/                           # Cross-project reusable packages
+    └── logger/
+```
+
+## Dependency Rule
+- domain → depends on nothing outside, pure Go structs and interfaces
+- usecase → depends only on domain; calls infrastructure through interfaces
+- infrastructure → implements usecase interfaces
+- handler → depends on usecase; handles HTTP layer
+
+## Go Conventions
+- Interfaces defined at the consumer side (usecase/), not implementation side (infrastructure/)
+- Error handling uses custom error types defined in domain/
+- Struct initialization uses New functions: NewOrderUseCase(), NewOrderRepo()
+- Context passed throughout: handler → usecase → repository
+
+## File Naming
+- snake_case: create_order.go
+- Test files: create_order_test.go
+- One type per file within same package
+
+## Testing
+- domain: pure unit tests
+- usecase: mock interfaces (using mockgen or hand-written mocks)
+- infrastructure: integration tests (using testcontainers or test DB)
+- handler: HTTP tests (using httptest)

package/templates/architectures/clean/go-std.md

@@ -0,0 +1,49 @@
+# Architecture: Clean Architecture (Go Standard Library)
+
+## Directory Structure
+```
+internal/
+├── domain/
+│   ├── entity/order.go            # Entities, Value Objects
+│   └── errors.go                  # Domain errors
+├── usecase/
+│   ├── create_order.go            # Use Cases
+│   └── interfaces.go              # Port interfaces
+├── infrastructure/
+│   ├── postgres/
+│   │   └── order_repo.go          # Repository implementation
+│   └── config/
+│       └── env.go                 # Environment configuration
+├── handler/
+│   └── http/
+│       ├── order_handler.go       # net/http handler
+│       ├── middleware/
+│       │   └── auth.go            # Middleware
+│       └── router.go              # http.ServeMux routes
+└── pkg/
+    └── logger/
+```
+
+## Dependency Rule
+- domain → depends on nothing outside, pure Go structs and interfaces
+- usecase → depends only on domain; calls infrastructure through interfaces
+- infrastructure → implements usecase interfaces
+- handler → depends on usecase; handles HTTP layer using net/http
+
+## Go Conventions
+- Use net/http ServeMux (Go 1.22+ enhanced routing) instead of external routers
+- Interfaces defined at the consumer side (usecase/)
+- Error handling uses custom error types defined in domain/
+- Struct initialization uses New functions
+- Context passed throughout: handler → usecase → repository
+
+## File Naming
+- snake_case: create_order.go
+- Test files: create_order_test.go
+- One type per file within same package
+
+## Testing
+- domain: pure unit tests
+- usecase: mock interfaces
+- infrastructure: integration tests (using testcontainers)
+- handler: HTTP tests (using httptest)

package/templates/architectures/clean/python-fastapi.md

@@ -0,0 +1,49 @@
+# Architecture: Clean Architecture (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── domain/
+│   ├── entities/order.py
+│   ├── value_objects/money.py
+│   ├── errors.py
+│   └── ports/order_repository.py   # Abstract base classes
+├── application/
+│   ├── use_cases/create_order.py
+│   └── dtos/order_dto.py
+├── infrastructure/
+│   ├── repositories/order_repository.py
+│   ├── database/
+│   │   ├── connection.py
+│   │   └── models/order_model.py    # SQLAlchemy models
+│   └── config.py
+├── interface/
+│   ├── routers/order_router.py
+│   ├── dependencies.py              # FastAPI dependency injection
+│   └── middleware/
+│       └── error_handler.py
+└── main.py                          # FastAPI app setup
+```
+
+## Dependency Rule
+- domain → depends on nothing outside, pure Python classes and ABCs
+- application → depends only on domain; use cases call externals via ports (ABCs)
+- infrastructure → implements domain ports
+- interface → depends on application; FastAPI routers + dependencies
+
+## Conventions
+- Ports defined as Abstract Base Classes (ABC) in domain/ports/
+- FastAPI dependency injection for wiring infrastructure to use cases
+- Pydantic models for DTOs and request/response validation
+- SQLAlchemy 2.0 style for ORM (if used)
+
+## File Naming
+- snake_case: create_order.py
+- Test files: test_create_order.py
+- One class per file or closely related classes grouped
+
+## Testing
+- domain: pure unit tests (pytest)
+- application: mock ports (pytest-mock)
+- infrastructure: integration tests (testcontainers)
+- interface: HTTP tests (httpx + TestClient)

package/templates/architectures/clean/typescript-express.md

@@ -0,0 +1,60 @@
+# Architecture: Clean Architecture (TypeScript + Express)
+
+## Layer-Based Structure
+Express uses a layer-based approach with Clean Architecture principles separating concerns into distinct directories.
+
+## Directory Structure
+```
+src/
+├── domain/
+│   ├── entities/order.entity.ts
+│   ├── value-objects/money.vo.ts
+│   └── errors/domain.error.ts
+├── application/
+│   ├── use-cases/create-order.use-case.ts
+│   ├── ports/
+│   │   ├── order.repository.port.ts
+│   │   └── payment.gateway.port.ts
+│   └── dtos/create-order.dto.ts
+├── infrastructure/
+│   ├── repositories/order.repository.ts
+│   ├── services/payment.gateway.ts
+│   ├── database/
+│   │   ├── connection.ts
+│   │   └── migrations/
+│   └── config/env.ts
+├── interface/
+│   ├── routes/order.routes.ts
+│   ├── controllers/order.controller.ts
+│   ├── middleware/
+│   │   ├── auth.middleware.ts
+│   │   └── error-handler.middleware.ts
+│   └── validators/order.validator.ts
+└── app.ts                         # Express app setup
+```
+
+## Dependency Rule
+- domain → depends on nothing outside, pure TypeScript classes
+- application → depends only on domain; use cases call externals via port interfaces
+- infrastructure → implements application ports
+- interface → depends on application; Express routes + controllers
+
+## Conventions
+- Dependency injection via constructor parameters or a simple DI container
+- Use Cases are single-purpose classes with an `execute()` method
+- Controllers handle HTTP concerns (req/res), delegate to Use Cases
+- Error handling via centralized error-handler middleware
+
+## File Naming
+- kebab-case: create-order.use-case.ts
+- Entity: *.entity.ts
+- Value Object: *.vo.ts
+- DTO: *.dto.ts
+- Port: *.port.ts
+- Repository: *.repository.ts
+
+## Testing
+- domain: pure unit tests, no mocks
+- application: mock ports
+- infrastructure: integration tests
+- interface: supertest HTTP tests

package/templates/architectures/clean/typescript-nestjs.md

@@ -0,0 +1,61 @@
+# Architecture: Clean Architecture (NestJS)
+
+## Module-Based Structure
+NestJS uses Module as its core organizational unit. Each feature gets its own Module, with Clean Architecture layers inside each Module.
+
+## Directory Structure
+```
+src/
+├── auth/                          # AuthModule
+│   ├── auth.module.ts
+│   ├── domain/
+│   │   └── entities/user.entity.ts
+│   ├── application/
+│   │   ├── use-cases/login.use-case.ts
+│   │   └── ports/auth.repository.port.ts
+│   ├── infrastructure/
+│   │   └── repositories/auth.repository.ts
+│   └── interface/
+│       ├── controllers/auth.controller.ts
+│       └── dtos/login.dto.ts
+├── order/                         # OrderModule
+│   ├── order.module.ts
+│   ├── domain/
+│   ├── application/
+│   ├── infrastructure/
+│   └── interface/
+├── shared/                        # SharedModule (cross-module shared)
+│   ├── shared.module.ts
+│   ├── guards/
+│   ├── interceptors/
+│   ├── filters/
+│   └── decorators/
+└── app.module.ts                  # Root module
+```
+
+## Dependency Rule
+- domain → depends on nothing outside, pure TypeScript classes
+- application → depends only on domain; use cases call externals via ports (interfaces)
+- infrastructure → implements application ports, injected into NestJS DI container
+- interface → depends on application; NestJS Controllers + DTOs
+
+## NestJS Conventions
+- Each Module registers providers, controllers, imports, exports in *.module.ts
+- Use Cases inject Port interfaces, receive Infrastructure implementations via NestJS DI
+- Cross-Module dependencies managed through exports + imports
+- Shared Module contains global guards, interceptors, filters, decorators
+
+## File Naming
+- kebab-case: create-order.use-case.ts
+- Entity: *.entity.ts
+- DTO: *.dto.ts
+- Controller: *.controller.ts
+- Repository: *.repository.ts
+- Port: *.port.ts
+- Module: *.module.ts
+
+## Testing
+- domain: pure unit tests, no mocks
+- application: mock ports (using NestJS Testing module)
+- infrastructure: integration tests
+- interface: E2E tests (using supertest)

package/templates/architectures/ddd/csharp-aspnet.md

@@ -0,0 +1,55 @@
+# Architecture: Domain-Driven Design (C# + ASP.NET Core)
+
+## Project Structure
+```
+src/
+├── Order.Domain/
+│   ├── Aggregates/OrderAggregate.cs
+│   ├── Entities/OrderItem.cs
+│   ├── ValueObjects/Money.cs
+│   ├── Events/OrderCreatedEvent.cs
+│   ├── Repositories/IOrderRepository.cs
+│   └── Services/PricingService.cs
+├── Order.Application/
+│   ├── Commands/CreateOrder/
+│   │   ├── CreateOrderCommand.cs
+│   │   └── CreateOrderHandler.cs
+│   ├── Queries/GetOrder/
+│   │   ├── GetOrderQuery.cs
+│   │   └── GetOrderHandler.cs
+│   └── DependencyInjection.cs
+├── Order.Infrastructure/
+│   ├── Persistence/
+│   │   ├── OrderRepository.cs
+│   │   └── OrderConfiguration.cs
+│   └── EventHandlers/OrderCreatedHandler.cs
+├── Order.WebApi/
+│   ├── Controllers/OrderController.cs
+│   └── Program.cs
+└── SharedKernel/
+    ├── AggregateRoot.cs
+    ├── DomainEvent.cs
+    └── ValueObject.cs
+```
+
+## Dependency Rule
+- Domain → depends on nothing, pure C# classes
+- Application → depends on Domain, uses MediatR for CQRS
+- Infrastructure → implements Domain interfaces
+- WebApi → depends on Application
+
+## DDD Conventions
+- Aggregate roots enforce invariants
+- MediatR for Command/Query separation
+- Domain Events via MediatR notifications
+- Value Objects implement Equals/GetHashCode
+
+## File Naming
+- PascalCase: OrderAggregate.cs
+- Folder-per-feature in Application
+
+## Testing
+- Domain: test aggregate invariants (xUnit)
+- Application: mock repositories (NSubstitute)
+- Infrastructure: integration tests
+- WebApi: E2E tests (WebApplicationFactory)

package/templates/architectures/ddd/go-gin.md

@@ -0,0 +1,53 @@
+# Architecture: Domain-Driven Design (Go + Gin)
+
+## Directory Structure
+```
+internal/
+├── order/                          # Order Bounded Context
+│   ├── domain/
+│   │   ├── aggregate/order.go      # Aggregate root
+│   │   ├── entity/order_item.go
+│   │   ├── valueobject/money.go
+│   │   ├── event/order_created.go
+│   │   ├── repository/order.go     # Interface
+│   │   └── service/pricing.go      # Domain service
+│   ├── application/
+│   │   ├── command/create_order.go
+│   │   ├── query/get_order.go
+│   │   └── handler/create_order_handler.go
+│   ├── infrastructure/
+│   │   ├── postgres/order_repo.go
+│   │   └── event/publisher.go
+│   └── handler/
+│       └── http/order_handler.go
+├── payment/                        # Payment Bounded Context
+│   └── ...
+├── shared/
+│   ├── domain/
+│   │   └── base_aggregate.go
+│   └── infrastructure/
+│       └── event_bus.go
+└── pkg/
+```
+
+## Dependency Rule
+- Aggregate roots are the only entry points to modify domain state
+- Domain events for cross-context communication
+- Application layer uses CQRS pattern
+- Infrastructure implements domain repository interfaces
+
+## DDD Conventions
+- Aggregates enforce invariants; modifications through aggregate methods
+- Value Objects are immutable (unexported fields + constructor)
+- Domain Events published after state changes
+- Anti-corruption layers between bounded contexts
+
+## File Naming
+- snake_case: create_order.go
+- One aggregate per package
+
+## Testing
+- domain: pure unit tests, test aggregate invariants
+- application: mock repositories
+- infrastructure: integration tests
+- handler: HTTP tests

package/templates/architectures/ddd/python-fastapi.md

@@ -0,0 +1,52 @@
+# Architecture: Domain-Driven Design (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── order/                          # Order Bounded Context
+│   ├── domain/
+│   │   ├── aggregates/order.py     # Aggregate root
+│   │   ├── entities/order_item.py
+│   │   ├── value_objects/money.py
+│   │   ├── events/order_created.py
+│   │   ├── repositories/order_repository.py  # ABC
+│   │   └── services/pricing_service.py
+│   ├── application/
+│   │   ├── commands/create_order.py
+│   │   ├── queries/get_order.py
+│   │   └── handlers/create_order_handler.py
+│   ├── infrastructure/
+│   │   ├── repositories/order_sqlalchemy_repo.py
+│   │   └── event_handlers/order_created_handler.py
+│   └── interface/
+│       ├── routers/order_router.py
+│       └── dtos/create_order_dto.py
+├── payment/
+│   └── ...
+├── shared/
+│   ├── domain/base_aggregate.py
+│   └── infrastructure/event_bus.py
+└── main.py
+```
+
+## Dependency Rule
+- Aggregate roots are the only entry points to modify domain state
+- Domain events for cross-context communication
+- Application layer uses CQRS pattern
+- Infrastructure implements domain repository ABCs
+
+## DDD Conventions
+- Aggregates enforce invariants via methods
+- Value Objects use frozen dataclasses
+- Domain Events as dataclass records
+- Anti-corruption layers between bounded contexts
+
+## File Naming
+- snake_case: create_order.py
+- Test files: test_create_order.py
+
+## Testing
+- domain: pure unit tests (pytest)
+- application: mock repositories
+- infrastructure: integration tests
+- interface: HTTP tests (httpx)

package/templates/architectures/ddd/typescript-nestjs.md

@@ -0,0 +1,62 @@
+# Architecture: Domain-Driven Design (NestJS)
+
+## Bounded Context Structure
+Each bounded context is a NestJS module with DDD tactical patterns.
+
+## Directory Structure
+```
+src/
+├── order/                          # Order Bounded Context
+│   ├── order.module.ts
+│   ├── domain/
+│   │   ├── aggregates/order.aggregate.ts
+│   │   ├── entities/order-item.entity.ts
+│   │   ├── value-objects/money.vo.ts
+│   │   ├── events/order-created.event.ts
+│   │   ├── repositories/order.repository.ts  # Interface
+│   │   └── services/pricing.domain-service.ts
+│   ├── application/
+│   │   ├── commands/create-order.command.ts
+│   │   ├── queries/get-order.query.ts
+│   │   └── handlers/create-order.handler.ts
+│   ├── infrastructure/
+│   │   ├── repositories/order.typeorm-repository.ts
+│   │   └── event-handlers/order-created.handler.ts
+│   └── interface/
+│       ├── controllers/order.controller.ts
+│       └── dtos/create-order.dto.ts
+├── payment/                        # Payment Bounded Context
+│   └── ...
+├── shared/
+│   ├── domain/
+│   │   └── base-aggregate.ts
+│   └── infrastructure/
+│       └── event-bus.ts
+└── app.module.ts
+```
+
+## Dependency Rule
+- Aggregate roots are the only entry points to modify domain state
+- Domain events for cross-context communication
+- Application layer uses CQRS (Commands + Queries)
+- Infrastructure implements domain repository interfaces
+
+## DDD Conventions
+- Aggregates enforce invariants; entity modifications go through aggregate methods
+- Value Objects are immutable
+- Domain Events published after state changes
+- Anti-corruption layers between bounded contexts
+- Ubiquitous language reflected in class and method names
+
+## File Naming
+- kebab-case: create-order.command.ts
+- Aggregate: *.aggregate.ts
+- Value Object: *.vo.ts
+- Domain Event: *.event.ts
+- Domain Service: *.domain-service.ts
+
+## Testing
+- domain: pure unit tests, test aggregate invariants
+- application: mock repositories, verify events
+- infrastructure: integration tests
+- interface: E2E tests

package/templates/architectures/hexagonal/csharp-aspnet.md

@@ -0,0 +1,45 @@
+# Architecture: Hexagonal / Ports & Adapters (C# + ASP.NET Core)
+
+## Project Structure
+```
+src/
+├── Core/
+│   ├── Domain/
+│   │   ├── Entities/Order.cs
+│   │   └── ValueObjects/Money.cs
+│   └── Ports/
+│       ├── Inbound/ICreateOrderUseCase.cs
+│       └── Outbound/IOrderRepository.cs
+├── Application/
+│   └── Services/OrderService.cs      # Implements inbound ports
+├── Adapters/
+│   ├── Inbound/
+│   │   └── WebApi/
+│   │       ├── Controllers/OrderController.cs
+│   │       └── Program.cs
+│   └── Outbound/
+│       ├── Persistence/
+│       │   ├── OrderRepository.cs
+│       │   └── ApplicationDbContext.cs
+│       └── Messaging/EventPublisher.cs
+```
+
+## Dependency Rule
+- Core → depends on nothing, pure C# interfaces and classes
+- Application → implements inbound ports, depends only on Core
+- Adapters → implement outbound ports or call inbound ports
+
+## Conventions
+- Inbound ports = use case interfaces
+- Outbound ports = infrastructure interfaces
+- DI registration wires adapters to ports in Program.cs
+- EF Core in outbound persistence adapter
+
+## File Naming
+- PascalCase: OrderService.cs
+- One class per file
+
+## Testing
+- Core: pure unit tests (xUnit)
+- Application: mock outbound ports (NSubstitute)
+- Adapters: integration tests (WebApplicationFactory)

package/templates/architectures/hexagonal/go-gin.md

@@ -0,0 +1,47 @@
+# Architecture: Hexagonal / Ports & Adapters (Go + Gin)
+
+## Directory Structure
+```
+internal/
+├── core/
+│   ├── domain/
+│   │   ├── order.go                # Entities, Value Objects
+│   │   └── errors.go               # Domain errors
+│   └── ports/
+│       ├── inbound.go              # Driving port interfaces
+│       └── outbound.go             # Driven port interfaces
+├── application/
+│   └── order_service.go            # Implements inbound ports
+├── adapters/
+│   ├── inbound/
+│   │   └── http/
+│   │       ├── order_handler.go    # Gin handler
+│   │       ├── middleware/
+│   │       └── router.go
+│   └── outbound/
+│       ├── postgres/
+│       │   └── order_repo.go
+│       └── redis/
+│           └── cache.go
+└── pkg/
+```
+
+## Dependency Rule
+- core → depends on nothing, pure Go types and interfaces
+- application → implements inbound ports, depends only on core
+- adapters → implement outbound ports or call inbound ports
+
+## Conventions
+- Ports defined as Go interfaces in core/ports/
+- Adapters implement port interfaces
+- Dependency injection via constructor functions
+- Context passed throughout
+
+## File Naming
+- snake_case: order_service.go
+- Test files: order_service_test.go
+
+## Testing
+- core: pure unit tests
+- application: mock outbound ports
+- adapters: integration tests per adapter