@pixelcraft-tw/spec 1.0.0

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/swift-ios.md

@@ -0,0 +1,69 @@
+# Architecture: Clean Architecture (iOS / SwiftUI)
+
+## Layer-Based Structure
+iOS app organized into Domain, Application, Infrastructure, and Presentation groups following Clean Architecture principles.
+
+## Directory Structure
+```
+Sources/
+├── Domain/
+│   ├── Entities/Order.swift
+│   ├── ValueObjects/Money.swift
+│   └── Errors/DomainError.swift
+├── Application/
+│   ├── UseCases/CreateOrderUseCase.swift
+│   ├── Ports/
+│   │   ├── OrderRepositoryPort.swift
+│   │   └── PaymentGatewayPort.swift
+│   └── DTOs/CreateOrderDTO.swift
+├── Infrastructure/
+│   ├── Repositories/OrderRepository.swift
+│   ├── Services/PaymentGateway.swift
+│   ├── Networking/APIClient.swift
+│   └── Persistence/
+│       └── SwiftDataModels.swift
+├── Presentation/
+│   ├── Views/OrderView.swift
+│   ├── ViewModels/OrderViewModel.swift
+│   ├── Navigation/AppRouter.swift
+│   └── Components/OrderCard.swift
+└── App.swift
+Tests/
+├── DomainTests/
+├── ApplicationTests/
+├── InfrastructureTests/
+└── PresentationTests/
+```
+
+## Dependency Rule
+- Domain → depends on nothing outside, pure Swift types
+- Application → depends only on Domain; use cases call externals via protocol ports
+- Infrastructure → implements Application ports (protocols)
+- Presentation → depends on Application; SwiftUI views + @Observable ViewModels
+
+## Recommended Dependencies
+- State Management: @Observable (Observation framework, built-in)
+- Networking: URLSession (built-in)
+- Navigation: NavigationStack (SwiftUI native)
+- Local Storage: SwiftData
+- DI: Factory pattern or manual injection
+
+## Conventions
+- Use Cases are structs/classes with a `execute()` method
+- ViewModels use @Observable macro, observed by SwiftUI views
+- Protocols define port boundaries between layers
+- Errors modeled as enums conforming to Error protocol
+
+## File Naming
+- PascalCase: CreateOrderUseCase.swift
+- Entity: *.swift under Entities/
+- Port: *Port.swift (protocol)
+- Repository: *Repository.swift
+- ViewModel: *ViewModel.swift
+- View: *View.swift
+
+## Testing
+- Domain: pure unit tests, XCTest
+- Application: mock ports with protocol conformance
+- Infrastructure: integration tests
+- Presentation: ViewInspector or snapshot tests

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

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

@@ -0,0 +1,43 @@
+# Architecture: Hexagonal / Ports & Adapters (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── core/
+│   ├── domain/
+│   │   ├── entities/order.py
+│   │   └── errors.py
+│   └── ports/
+│       ├── inbound/create_order_port.py   # ABC interfaces
+│       └── outbound/order_repository.py   # ABC interfaces
+├── application/
+│   └── services/order_service.py          # Implements inbound ports
+├── adapters/
+│   ├── inbound/
+│   │   └── http/
+│   │       ├── order_router.py
+│   │       └── dependencies.py
+│   └── outbound/
+│       ├── persistence/order_repository.py
+│       └── messaging/event_publisher.py
+└── main.py
+```
+
+## Dependency Rule
+- core → depends on nothing, pure Python ABCs and dataclasses
+- application → implements inbound ports, depends only on core
+- adapters → implement outbound ports or call inbound ports
+
+## Conventions
+- Ports defined as Abstract Base Classes in core/ports/
+- FastAPI dependency injection wires adapters to ports
+- Pydantic for DTOs at adapter boundary
+
+## File Naming
+- snake_case: order_service.py
+- Test files: test_order_service.py
+
+## Testing
+- core: pure unit tests (pytest)
+- application: mock outbound ports
+- adapters: integration tests per adapter

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

@@ -0,0 +1,44 @@
+# Architecture: Hexagonal / Ports & Adapters (NestJS)
+
+## Directory Structure
+```
+src/
+├── core/
+│   ├── domain/
+│   │   ├── entities/order.entity.ts
+│   │   └── value-objects/money.vo.ts
+│   └── ports/
+│       ├── inbound/create-order.port.ts    # Driving ports (use case interfaces)
+│       └── outbound/order.repository.port.ts # Driven ports
+├── application/
+│   └── services/order.service.ts           # Implements inbound ports
+├── adapters/
+│   ├── inbound/
+│   │   ├── http/order.controller.ts        # REST adapter
+│   │   └── grpc/order.grpc.ts              # gRPC adapter
+│   └── outbound/
+│       ├── persistence/order.repository.ts # DB adapter
+│       └── messaging/event.publisher.ts    # Message queue adapter
+└── app.module.ts
+```
+
+## Dependency Rule
+- core (domain + ports) → depends on nothing, defines all interfaces
+- application → implements inbound ports, depends on core only
+- adapters → implement outbound ports or call inbound ports
+
+## Conventions
+- Inbound ports = use case interfaces (what the app can do)
+- Outbound ports = infrastructure interfaces (what the app needs)
+- Adapters are interchangeable (swap DB, swap transport)
+- NestJS modules wire adapters to ports via DI
+
+## File Naming
+- kebab-case: create-order.port.ts
+- Port: *.port.ts
+- Adapter suffix indicates type: *.controller.ts, *.repository.ts
+
+## Testing
+- core: pure unit tests
+- application: mock outbound ports
+- adapters: integration tests per adapter