docs: initialize engineering starter kit
This commit is contained in:
AzuTear
@@ -0,0 +1,193 @@
|
||||
# Architecture
|
||||
|
||||
This document describes the structure, boundaries, flows, and technical rules of
|
||||
the system.
|
||||
|
||||
For project intent and runtime facts, see [PROJECT.md](PROJECT.md).
|
||||
For coding standards, see [CONVENTIONS.md](CONVENTIONS.md).
|
||||
For recorded trade-offs, see [DECISIONS.md](DECISIONS.md).
|
||||
|
||||
## High-Level Overview
|
||||
|
||||
`{{PROJECT_NAME}}` uses `{{ARCHITECTURE_STYLE}}` to support
|
||||
`{{PRIMARY_USE_CASES}}`.
|
||||
|
||||
Replace this section with a concise explanation of the system's major parts,
|
||||
their responsibilities, and the constraints that shaped the architecture.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User["User or External Client"]
|
||||
Interface["Interface Layer<br/>API, UI, CLI, Worker"]
|
||||
Application["Application Layer<br/>Use cases and orchestration"]
|
||||
Domain["Domain Layer<br/>Rules and invariants"]
|
||||
Infrastructure["Infrastructure Layer<br/>Database, queues, files, services"]
|
||||
External["External Systems"]
|
||||
|
||||
User --> Interface
|
||||
Interface --> Application
|
||||
Application --> Domain
|
||||
Application --> Infrastructure
|
||||
Infrastructure --> External
|
||||
```
|
||||
|
||||
## Architecture Style
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Style | `{{ARCHITECTURE_STYLE}}` |
|
||||
| Primary reason | `{{ARCHITECTURE_REASON}}` |
|
||||
| Main trade-off | `{{ARCHITECTURE_TRADE_OFF}}` |
|
||||
| Related decision | [DECISIONS.md](DECISIONS.md) |
|
||||
|
||||
Common examples include layered architecture, modular monolith, microservices,
|
||||
event-driven architecture, hexagonal architecture, desktop MVC/MVVM, or
|
||||
game-specific entity/component systems.
|
||||
|
||||
## Folder Structure
|
||||
|
||||
```text
|
||||
{{PROJECT_ROOT}}/
|
||||
{{SOURCE_FOLDER}}/
|
||||
{{TEST_FOLDER}}/
|
||||
{{DOCS_FOLDER}}/
|
||||
{{BUILD_FOLDER}}/
|
||||
```
|
||||
|
||||
| Folder | Responsibility |
|
||||
| --- | --- |
|
||||
| `{{FOLDER}}` | `{{FOLDER_RESPONSIBILITY}}` |
|
||||
|
||||
Keep generated files, build outputs, and framework artifacts out of source
|
||||
folders unless the framework requires them.
|
||||
|
||||
## Module Responsibilities
|
||||
|
||||
| Module | Responsibility | Owned Data | Public Interface |
|
||||
| --- | --- | --- | --- |
|
||||
| `{{MODULE_NAME}}` | `{{MODULE_RESPONSIBILITY}}` | `{{OWNED_DATA}}` | `{{PUBLIC_INTERFACE}}` |
|
||||
|
||||
Modules should have clear ownership. Shared utilities should remain small and
|
||||
generic; domain behavior belongs with the module that owns the domain concept.
|
||||
|
||||
## Dependency Rules
|
||||
|
||||
Define allowed dependencies explicitly.
|
||||
|
||||
- `{{DEPENDENCY_RULE_1}}`
|
||||
- `{{DEPENDENCY_RULE_2}}`
|
||||
- `{{DEPENDENCY_RULE_3}}`
|
||||
|
||||
Recommended default:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
UI["UI, API, CLI, Worker"]
|
||||
App["Application"]
|
||||
Domain["Domain"]
|
||||
Infra["Infrastructure"]
|
||||
|
||||
UI --> App
|
||||
App --> Domain
|
||||
App --> Infra
|
||||
Infra --> Domain
|
||||
```
|
||||
|
||||
Domain code should not depend on delivery mechanisms, databases, network
|
||||
clients, or framework-specific runtime concerns unless the project intentionally
|
||||
uses an architecture where that trade-off is accepted and recorded.
|
||||
|
||||
## Request Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Interface
|
||||
participant Application
|
||||
participant Domain
|
||||
participant Infrastructure
|
||||
|
||||
Client->>Interface: Request or command
|
||||
Interface->>Application: Validate transport shape
|
||||
Application->>Domain: Execute business rule
|
||||
Application->>Infrastructure: Persist or integrate
|
||||
Infrastructure-->>Application: Result
|
||||
Application-->>Interface: Response model
|
||||
Interface-->>Client: Response
|
||||
```
|
||||
|
||||
Document deviations for async jobs, desktop workflows, games, or event-driven
|
||||
flows.
|
||||
|
||||
## Data Flow
|
||||
|
||||
| Data | Source | Owner | Storage | Consumers |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `{{DATA_ENTITY}}` | `{{DATA_SOURCE}}` | `{{DATA_OWNER}}` | `{{DATA_STORAGE}}` | `{{DATA_CONSUMERS}}` |
|
||||
|
||||
Data ownership should be clear before adding shared tables, shared schemas,
|
||||
cross-service writes, or replicated state.
|
||||
|
||||
## Domain Model
|
||||
|
||||
| Concept | Meaning | Invariants |
|
||||
| --- | --- | --- |
|
||||
| `{{DOMAIN_CONCEPT}}` | `{{DOMAIN_MEANING}}` | `{{DOMAIN_INVARIANTS}}` |
|
||||
|
||||
Use this section for durable business concepts, not framework models or DTOs.
|
||||
|
||||
## Integration Points
|
||||
|
||||
| Integration | Direction | Protocol | Reliability Expectations |
|
||||
| --- | --- | --- | --- |
|
||||
| `{{INTEGRATION_NAME}}` | `{{INBOUND_OR_OUTBOUND}}` | `{{PROTOCOL}}` | `{{RELIABILITY_EXPECTATIONS}}` |
|
||||
|
||||
For each integration, document authentication, retry behavior, timeouts,
|
||||
idempotency, and failure handling.
|
||||
|
||||
## Security
|
||||
|
||||
| Area | Policy |
|
||||
| --- | --- |
|
||||
| Authentication | `{{AUTHENTICATION_POLICY}}` |
|
||||
| Authorization | `{{AUTHORIZATION_POLICY}}` |
|
||||
| Secrets | `{{SECRETS_POLICY}}` |
|
||||
| Input validation | `{{INPUT_VALIDATION_POLICY}}` |
|
||||
| Output encoding | `{{OUTPUT_ENCODING_POLICY}}` |
|
||||
| Audit logging | `{{AUDIT_LOGGING_POLICY}}` |
|
||||
| Dependency security | `{{DEPENDENCY_SECURITY_POLICY}}` |
|
||||
|
||||
Security-sensitive decisions should be recorded in [DECISIONS.md](DECISIONS.md).
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error Type | Handling Policy | User/Client Response |
|
||||
| --- | --- | --- |
|
||||
| Validation error | `{{VALIDATION_ERROR_POLICY}}` | `{{VALIDATION_RESPONSE}}` |
|
||||
| Domain error | `{{DOMAIN_ERROR_POLICY}}` | `{{DOMAIN_RESPONSE}}` |
|
||||
| Infrastructure error | `{{INFRASTRUCTURE_ERROR_POLICY}}` | `{{INFRASTRUCTURE_RESPONSE}}` |
|
||||
| Unexpected error | `{{UNEXPECTED_ERROR_POLICY}}` | `{{UNEXPECTED_RESPONSE}}` |
|
||||
|
||||
Errors should preserve enough diagnostic context for operators without exposing
|
||||
secrets or internal implementation details to users.
|
||||
|
||||
## Performance
|
||||
|
||||
| Concern | Expectation | Measurement |
|
||||
| --- | --- | --- |
|
||||
| Latency | `{{LATENCY_EXPECTATION}}` | `{{LATENCY_MEASUREMENT}}` |
|
||||
| Throughput | `{{THROUGHPUT_EXPECTATION}}` | `{{THROUGHPUT_MEASUREMENT}}` |
|
||||
| Resource usage | `{{RESOURCE_EXPECTATION}}` | `{{RESOURCE_MEASUREMENT}}` |
|
||||
|
||||
Document known hot paths and the expected performance test strategy.
|
||||
|
||||
## Scalability
|
||||
|
||||
| Dimension | Current Strategy | Future Strategy |
|
||||
| --- | --- | --- |
|
||||
| Traffic | `{{TRAFFIC_STRATEGY}}` | `{{TRAFFIC_FUTURE_STRATEGY}}` |
|
||||
| Data volume | `{{DATA_VOLUME_STRATEGY}}` | `{{DATA_VOLUME_FUTURE_STRATEGY}}` |
|
||||
| Team size | `{{TEAM_SCALE_STRATEGY}}` | `{{TEAM_SCALE_FUTURE_STRATEGY}}` |
|
||||
|
||||
Scalability work should be driven by measured pressure or clear product
|
||||
requirements, not premature complexity.
|
||||
Reference in New Issue
Block a user