@pixelcraft-tw/spec 1.0.0

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

@@ -0,0 +1,45 @@
+# Architecture: Layered / Three-Tier (C# + ASP.NET Core)
+
+## Project Structure
+```
+src/
+├── Controllers/
+│   ├── OrderController.cs
+│   └── AuthController.cs
+├── Services/
+│   ├── IOrderService.cs
+│   ├── OrderService.cs
+│   └── IAuthService.cs
+├── Repositories/
+│   ├── IOrderRepository.cs
+│   ├── OrderRepository.cs
+│   └── ApplicationDbContext.cs
+├── Models/
+│   ├── Order.cs
+│   └── User.cs
+├── DTOs/
+│   ├── CreateOrderDto.cs
+│   └── LoginDto.cs
+├── Middleware/
+│   └── ExceptionHandlerMiddleware.cs
+└── Program.cs
+```
+
+## Layer Dependencies
+- Controllers → Services → Repositories → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- Interface-based DI for Services and Repositories
+- EF Core for data access
+- DTOs at controller boundary
+- Middleware for cross-cutting concerns
+
+## File Naming
+- PascalCase: OrderService.cs
+- Interface prefix: IOrderService.cs
+
+## Testing
+- Services: unit tests (xUnit + NSubstitute)
+- Controllers: unit tests with mocked services
+- Repositories: integration tests (WebApplicationFactory)

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

@@ -0,0 +1,41 @@
+# Architecture: Layered / Three-Tier (Go + Gin)
+
+## Directory Structure
+```
+internal/
+├── handler/
+│   ├── order_handler.go
+│   ├── auth_handler.go
+│   ├── middleware/
+│   └── router.go
+├── service/
+│   ├── order_service.go
+│   └── auth_service.go
+├── repository/
+│   ├── order_repo.go
+│   └── user_repo.go
+├── model/
+│   ├── order.go
+│   └── user.go
+└── config/
+    └── env.go
+```
+
+## Layer Dependencies
+- Handler → Service → Repository → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- Handlers handle HTTP concerns (Gin context)
+- Services contain business logic, accept/return domain models
+- Repositories handle data access
+- Interfaces defined at consumer side for testability
+
+## File Naming
+- snake_case: order_service.go
+- Test files: order_service_test.go
+
+## Testing
+- services: unit tests with mocked repositories
+- handlers: HTTP tests (httptest)
+- repositories: integration tests

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

@@ -0,0 +1,42 @@
+# Architecture: Layered / Three-Tier (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── routers/
+│   ├── order_router.py
+│   └── auth_router.py
+├── services/
+│   ├── order_service.py
+│   └── auth_service.py
+├── repositories/
+│   ├── order_repository.py
+│   └── user_repository.py
+├── models/
+│   ├── order.py
+│   └── user.py
+├── schemas/
+│   ├── order_schema.py           # Pydantic models
+│   └── auth_schema.py
+├── config.py
+└── main.py
+```
+
+## Layer Dependencies
+- Routers → Services → Repositories → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- FastAPI dependency injection for wiring
+- Pydantic schemas at router boundary
+- Services contain business logic
+- Repositories handle SQLAlchemy queries
+
+## File Naming
+- snake_case: order_service.py
+- Test files: test_order_service.py
+
+## Testing
+- services: unit tests (pytest + mock)
+- routers: HTTP tests (TestClient)
+- repositories: integration tests

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

@@ -0,0 +1,48 @@
+# Architecture: Layered / Three-Tier (NestJS)
+
+## Directory Structure
+```
+src/
+├── controllers/
+│   ├── order.controller.ts
+│   └── auth.controller.ts
+├── services/
+│   ├── order.service.ts
+│   └── auth.service.ts
+├── repositories/
+│   ├── order.repository.ts
+│   └── user.repository.ts
+├── entities/
+│   ├── order.entity.ts
+│   └── user.entity.ts
+├── dtos/
+│   ├── create-order.dto.ts
+│   └── login.dto.ts
+├── guards/
+├── interceptors/
+├── pipes/
+└── app.module.ts
+```
+
+## Layer Dependencies
+- Controllers → Services → Repositories → Database
+- Each layer only depends on the layer directly below
+
+## Conventions
+- Controllers handle HTTP, validate input via DTOs + Pipes
+- Services contain business logic
+- Repositories handle data access (TypeORM/Prisma/MikroORM)
+- NestJS DI wires everything together
+
+## File Naming
+- kebab-case: order.service.ts, create-order.dto.ts
+- Controller: *.controller.ts
+- Service: *.service.ts
+- Repository: *.repository.ts
+- Entity: *.entity.ts
+
+## Testing
+- services: unit tests with mocked repositories
+- controllers: unit tests with mocked services
+- repositories: integration tests
+- E2E: supertest

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

@@ -0,0 +1,45 @@
+# Architecture: Modular Monolith (C# + ASP.NET Core)
+
+## Project Structure
+```
+src/
+├── Modules/
+│   ├── Order/
+│   │   ├── OrderModule.cs
+│   │   ├── Controllers/OrderController.cs
+│   │   ├── Services/OrderService.cs
+│   │   ├── Repositories/OrderRepository.cs
+│   │   ├── Models/Order.cs
+│   │   ├── DTOs/CreateOrderDto.cs
+│   │   └── Events/OrderCreatedEvent.cs
+│   ├── Payment/
+│   │   └── ...
+│   └── User/
+│       └── ...
+├── Shared/
+│   ├── Database/ApplicationDbContext.cs
+│   ├── Events/IEventBus.cs
+│   └── Middleware/
+└── Program.cs
+```
+
+## Module Boundaries
+- Each module is self-contained with controllers, services, repositories
+- Modules communicate via events or explicit interfaces
+- No direct database access across module boundaries
+- Shared for cross-cutting concerns only
+
+## Conventions
+- Each module has a registration extension method (AddOrderModule)
+- Inter-module communication via MediatR notifications
+- Each module owns its EF Core configurations
+- Modules register their own DI services
+
+## File Naming
+- PascalCase: OrderService.cs
+- One module = one folder under Modules/
+
+## Testing
+- Per-module unit tests (xUnit)
+- Integration tests per module
+- Cross-module E2E tests

package/templates/architectures/modular/dart-flutter.md

@@ -0,0 +1,64 @@
+# Architecture: Modular (Flutter)
+
+## Directory Structure
+```
+lib/
+├── features/
+│   ├── order/
+│   │   ├── data/
+│   │   │   ├── order_repository.dart
+│   │   │   └── order_api.dart
+│   │   ├── domain/
+│   │   │   └── order.dart
+│   │   ├── presentation/
+│   │   │   ├── order_page.dart
+│   │   │   ├── order_provider.dart
+│   │   │   └── widgets/order_card.dart
+│   │   └── order_module.dart
+│   ├── payment/
+│   │   └── ...
+│   └── user/
+│       └── ...
+├── shared/
+│   ├── database/app_database.dart
+│   ├── networking/dio_client.dart
+│   ├── widgets/loading_indicator.dart
+│   └── providers/shared_providers.dart
+├── router/app_router.dart
+└── main.dart
+test/
+├── features/
+│   ├── order/
+│   └── payment/
+└── shared/
+integration_test/
+└── app_test.dart
+```
+
+## Module Boundaries
+- Each feature is self-contained with its own data, domain, presentation layers
+- Features communicate via Riverpod providers or explicit public APIs
+- No direct data access across feature boundaries
+- shared/ for truly cross-cutting concerns only
+
+## Recommended Dependencies
+- State Management: Riverpod (per-feature scope)
+- Networking: dio
+- Navigation: go_router (nested routing per feature)
+- Local Storage: drift (per-feature DB or shared)
+- DI: Riverpod (self-contained)
+
+## Conventions
+- Feature module entry point exports only its public API (providers, routes)
+- Inter-feature communication via shared providers or event streams
+- Each feature owns its own data models and repositories
+- go_router ShellRoute per feature for nested navigation
+
+## File Naming
+- snake_case: order_repository.dart, order_page.dart
+- One feature = one directory under features/
+
+## Testing
+- Per-feature unit tests
+- Per-feature widget tests
+- Cross-feature integration tests in integration_test/

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

@@ -0,0 +1,47 @@
+# Architecture: Modular Monolith (Go + Gin)
+
+## Directory Structure
+```
+internal/
+├── modules/
+│   ├── order/
+│   │   ├── handler.go
+│   │   ├── service.go
+│   │   ├── repository.go
+│   │   ├── model.go
+│   │   ├── events.go
+│   │   └── routes.go
+│   ├── payment/
+│   │   └── ...
+│   └── user/
+│       └── ...
+├── shared/
+│   ├── database/
+│   ├── events/event_bus.go
+│   └── middleware/
+├── config/
+│   └── env.go
+└── cmd/
+    └── main.go
+```
+
+## Module Boundaries
+- Each module is a Go package with its own handler, service, repository
+- Modules communicate via events or explicit function calls
+- No direct database access across module boundaries
+- Shared package for cross-cutting concerns
+
+## Conventions
+- Each module registers its own routes via a Setup function
+- Inter-module communication via event bus
+- Each module owns its database tables
+- Module interfaces defined per module
+
+## File Naming
+- snake_case: order_service.go
+- One module = one package under modules/
+
+## Testing
+- Per-module unit tests
+- Integration tests per module
+- Cross-module E2E tests

package/templates/architectures/modular/kotlin-android.md

@@ -0,0 +1,68 @@
+# Architecture: Modular (Android / Kotlin)
+
+## Directory Structure
+```
+:app/                                          # Application module
+├── src/main/java/com/example/app/
+│   ├── navigation/AppNavigation.kt
+│   ├── di/AppModule.kt
+│   └── App.kt
+:feature:order/
+├── src/main/java/com/example/feature/order/
+│   ├── ui/
+│   │   ├── OrderScreen.kt
+│   │   └── OrderViewModel.kt
+│   ├── domain/
+│   │   ├── Order.kt
+│   │   └── OrderUseCase.kt
+│   ├── data/
+│   │   ├── OrderRepository.kt
+│   │   └── OrderApi.kt
+│   └── di/OrderModule.kt
+:feature:payment/
+│   └── ...
+:feature:user/
+│   └── ...
+:core:network/
+├── src/main/java/com/example/core/network/
+│   ├── ApiClient.kt
+│   └── di/NetworkModule.kt
+:core:database/
+├── src/main/java/com/example/core/database/
+│   ├── AppDatabase.kt
+│   └── di/DatabaseModule.kt
+:core:ui/
+├── src/main/java/com/example/core/ui/
+│   ├── theme/Theme.kt
+│   └── components/LoadingIndicator.kt
+```
+
+## Module Boundaries
+- Each :feature:* module is self-contained with ui, domain, data layers
+- Features depend on :core:* modules but never on other features
+- Inter-feature navigation via Navigation Compose nested graphs
+- :core:* modules provide shared infrastructure
+
+## Recommended Dependencies
+- State Management: Hilt + StateFlow + Compose State
+- Networking: Retrofit + OkHttp (in :core:network)
+- DI: Hilt (per-module @Module)
+- Navigation: Navigation Compose (nested graphs per feature)
+- Local Storage: Room (in :core:database)
+- Async: Kotlin Coroutines + Flow
+
+## Conventions
+- Feature modules expose only their navigation graph entry point
+- Hilt @Module scoped per feature module
+- Navigation Compose nested NavGraph per feature
+- Room database in :core:database, DAOs accessible via DI
+
+## File Naming
+- PascalCase: OrderViewModel.kt, OrderScreen.kt
+- One feature = one Gradle module under :feature:*
+- Core modules under :core:*
+
+## Testing
+- Per-feature unit tests
+- Per-feature Compose UI tests
+- Cross-feature E2E tests in :app

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

@@ -0,0 +1,45 @@
+# Architecture: Modular Monolith (Python + FastAPI)
+
+## Directory Structure
+```
+src/
+├── modules/
+│   ├── order/
+│   │   ├── router.py
+│   │   ├── service.py
+│   │   ├── repository.py
+│   │   ├── models.py
+│   │   ├── schemas.py
+│   │   └── events.py
+│   ├── payment/
+│   │   └── ...
+│   └── user/
+│       └── ...
+├── shared/
+│   ├── database/connection.py
+│   ├── events/event_bus.py
+│   └── middleware/
+├── config.py
+└── main.py
+```
+
+## Module Boundaries
+- Each module is a Python package with its own router, service, repository
+- Modules communicate via events or explicit imports of public APIs
+- No direct database access across module boundaries
+- Shared package for cross-cutting concerns
+
+## Conventions
+- Each module registers its own FastAPI router
+- Inter-module communication via event bus
+- Each module owns its SQLAlchemy models
+- Public API defined in module __init__.py
+
+## File Naming
+- snake_case: order_service.py
+- One module = one package under modules/
+
+## Testing
+- Per-module unit tests (pytest)
+- Integration tests per module
+- Cross-module E2E tests

package/templates/architectures/modular/swift-ios.md

@@ -0,0 +1,55 @@
+# Architecture: Modular (iOS / SwiftUI)
+
+## Directory Structure
+```
+Sources/
+├── Features/
+│   ├── Order/
+│   │   ├── Views/OrderView.swift
+│   │   ├── ViewModels/OrderViewModel.swift
+│   │   ├── Models/Order.swift
+│   │   ├── Services/OrderService.swift
+│   │   └── Navigation/OrderRouter.swift
+│   ├── Payment/
+│   │   └── ...
+│   └── User/
+│       └── ...
+├── Shared/
+│   ├── Networking/APIClient.swift
+│   ├── Persistence/SharedDatabase.swift
+│   ├── Components/LoadingView.swift
+│   └── Extensions/
+└── App.swift
+Tests/
+├── OrderTests/
+├── PaymentTests/
+└── SharedTests/
+```
+
+## Module Boundaries
+- Each feature is self-contained with its own Views, ViewModels, Models, Services
+- Features communicate via shared protocols or notification/event patterns
+- No direct data access across feature boundaries
+- Shared/ for truly cross-cutting concerns only
+
+## Recommended Dependencies
+- State Management: @Observable (Observation framework)
+- Networking: URLSession (built-in)
+- Navigation: NavigationStack per feature
+- Local Storage: SwiftData (shared)
+- DI: Factory pattern
+
+## Conventions
+- Feature entry point exposes only its root view and public protocols
+- ViewModels use @Observable macro
+- NavigationStack scoped per feature with coordinator pattern
+- SwiftData models in Shared/ when used across features
+
+## File Naming
+- PascalCase: OrderViewModel.swift, OrderView.swift
+- One feature = one directory under Features/
+
+## Testing
+- Per-feature unit tests with XCTest
+- Per-feature UI tests
+- Cross-feature integration tests

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

@@ -0,0 +1,48 @@
+# Architecture: Modular Monolith (NestJS)
+
+## Directory Structure
+```
+src/
+├── modules/
+│   ├── order/
+│   │   ├── order.module.ts
+│   │   ├── order.controller.ts
+│   │   ├── order.service.ts
+│   │   ├── order.repository.ts
+│   │   ├── entities/order.entity.ts
+│   │   ├── dtos/create-order.dto.ts
+│   │   └── events/order-created.event.ts
+│   ├── payment/
+│   │   ├── payment.module.ts
+│   │   └── ...
+│   └── user/
+│       ├── user.module.ts
+│       └── ...
+├── shared/
+│   ├── shared.module.ts
+│   ├── database/
+│   ├── events/event-bus.ts
+│   └── guards/
+└── app.module.ts
+```
+
+## Module Boundaries
+- Each module is self-contained with its own controller, service, repository, entities
+- Modules communicate via events or explicit public APIs (exported services)
+- No direct database access across module boundaries
+- Shared module for truly cross-cutting concerns only
+
+## Conventions
+- Module exports define the public API
+- Inter-module communication via EventEmitter or message bus
+- Each module owns its database tables
+- NestJS DI scoped per module
+
+## File Naming
+- kebab-case: order.service.ts, create-order.dto.ts
+- One module = one directory under modules/
+
+## Testing
+- Per-module unit tests
+- Integration tests per module
+- Cross-module E2E tests

package/templates/architectures/mvvm/dart-flutter.md

@@ -0,0 +1,69 @@
+# Architecture: MVVM (Flutter)
+
+## Pattern Overview
+Flutter app organized into Models, Views, ViewModels, and Services under `lib/`. ViewModels hold UI state and logic; Views are pure widgets that observe ViewModel state.
+
+## Directory Structure
+```
+lib/
+├── models/
+│   ├── order.dart
+│   └── user.dart
+├── views/
+│   ├── order_list_view.dart
+│   ├── order_detail_view.dart
+│   └── widgets/
+│       └── order_card.dart
+├── viewmodels/
+│   ├── order_list_viewmodel.dart
+│   └── order_detail_viewmodel.dart
+├── services/
+│   ├── order_service.dart
+│   └── auth_service.dart
+├── repositories/
+│   ├── order_repository.dart
+│   └── user_repository.dart
+└── main.dart
+test/
+├── models/
+├── viewmodels/
+├── services/
+└── repositories/
+integration_test/
+└── app_test.dart
+```
+
+## Responsibility Split
+- Models → plain Dart data classes, no framework dependency
+- Views → StatelessWidget / HookWidget, render UI from ViewModel state, dispatch user actions to ViewModel
+- ViewModels → hold UI state, expose state streams, call Services/Repositories
+- Services → API calls, external integrations (HTTP, WebSocket)
+- Repositories → data access abstraction over local + remote sources
+
+## Recommended Dependencies
+- State Management: Riverpod (StateNotifier / AsyncNotifier)
+- Networking: dio
+- Navigation: go_router
+- Local Storage: drift (SQL), shared_preferences (KV)
+- DI: Riverpod (self-contained)
+
+## Conventions
+- One ViewModel per screen or major UI section
+- ViewModel is a Riverpod Notifier/AsyncNotifier, never a raw ChangeNotifier
+- Views read ViewModel via `ref.watch()`; never call Services directly
+- Models are immutable (use `freezed` or manual `copyWith`)
+
+## File Naming
+- snake_case: order_list_viewmodel.dart
+- View: *_view.dart
+- ViewModel: *_viewmodel.dart
+- Service: *_service.dart
+- Repository: *_repository.dart
+- Model: descriptive name under models/
+
+## Testing
+- Models: pure unit tests
+- ViewModels: unit tests with mocked services/repositories
+- Services: integration tests or mocked HTTP (dio adapter)
+- Views: widget tests with ProviderScope overrides
+- integration_test/: full app flow tests