Engineering Architecture & Data Flow Guideline
Department
Table of Contents
Purpose
This guideline defines the essential engineering architecture and data flow standards for Technology at Kiluth.
| Outcome |
|---|
| Systems have clear responsibility boundaries, predictable data flow, and maintainable code that can evolve without breaking integrations. |
Scope
Applies to web applications, CLI tools, microservices, background jobs, and integrations built by Technology.
This document focuses on code organization, data flow patterns, and responsibility boundaries. It does not prescribe languages, frameworks, or deployment choices.
Definitions
| Term | Definition |
|---|---|
| Contract / DTO | A data structure that defines an external boundary (request/response/event payload). It is the “agreement” across systems or layers |
| Business entity | A domain concept used inside application logic (e.g., User, Order) |
| Storage model | A persistence representation (DB schema/record/file format) used inside data access |
| Entry point | Delivery mechanism boundary (HTTP handler/controller, CLI command, job handler, event handler) |
| Application logic | Business rules and orchestration (services/use cases) |
| Data access | Repositories/adapters that read/write storage or call external systems |
Operating Model
| Operating Model | |
|---|---|
| 1 | Asana is the system of record for work tracking, approvals, and handoffs. |
| 2 | Use checkpoints and decision points: don’t move forward until the previous step is “done”, and branches are explicit. |
| 3 | Handoff order: upstream defines handoff artifacts/exit criteria; downstream defines execution after handoff. |
Core Architecture Pattern
Data structure types (keep them separate)
| Type | Used for | Lives in |
|---|---|---|
| Contract / DTO | External boundaries | Entry points / API layer |
| Business entity | Core business logic | Application logic |
| Storage model | Persistence representation | Data access |
Layer responsibilities
Dependency flow is one-way:
Entry point → Application logic → Data access → Storage / External systems
| Layer | Responsibility | Must not |
|---|---|---|
| Contracts / DTOs | Define boundary data shapes | Contain business rules, leak storage structure |
| Entry points | Parse/validate input shape, map DTO ↔ entity, call application logic, map errors to interface response | Contain business logic, access storage directly |
| Application logic | Enforce business rules, coordinate data access, work with entities | Know about HTTP/CLI formats, work with DTOs/storage models |
| Data access | Read/write storage, handle queries/transactions, map storage ↔ entity; integrate external services | Make business decisions, expose storage/external details upward |
| Storage models | Represent persistence (tables/records/files) | Leak into application logic or entry points |
| Outcome |
|---|
| Code is easier to test, safer to change, and clearer to review. |
Contract-First Workflow (Step-by-step)
Use this workflow for new systems and significant changes.
| Step | |
|---|---|
| 1 | Define contracts first (DTOs at every boundary). Agree on data shapes before implementation |
| 2 | Define business entities required to serve the contracts |
| 3 | Implement application logic using entities only |
| 4 | Implement data access (storage/external) and translation (entity ↔ storage / entity ↔ external) |
| 5 | Implement entry points and translation (DTO ↔ entity) |
| 6 | Add minimum observability + tests + documentation (see below) |
| Outcome |
|---|
| Boundaries are explicit and changes are visible and reviewable. |
Minimum Engineering Requirements
Validation & errors (layered)
| Where | What to validate | Notes |
|---|---|---|
| Entry points | Input shape/parsing, basic required fields | Treat inputs as untrusted; map to contracts |
| Application logic | Business rules (always) | The source of truth for business validation |
Standard error shape:
{ code: string, message: string, details?: object }
| Outcome |
|---|
| Failures are consistent, debuggable, and safe to expose externally. |
Observability (minimum)
Every use case should be diagnosable without ad-hoc logging.
| Minimum logging | |
|---|---|
| 1 | Log at entry points for start + completion (status, latency) |
| 2 | Include correlation IDs when available (requestId/traceId) + useCase |
| 3 | Do not log secrets; avoid full payload logs by default |
Configuration & secrets
| Rule | Description |
|---|---|
| Config flows outside-in | Read config in composition root / entry point setup; inject into inner layers |
| Never store secrets in code/contracts/logs | Use env/secret managers; redact sensitive values |
Security (minimum)
| Minimum expectations | |
|---|---|
| 1 | Parameterized queries (no SQL string concatenation) |
| 2 | Safe error messages externally; log details internally with correlation IDs |
| 3 | Authorization decisions belong in application logic (when applicable) |
Testing (minimum)
| Layer | Test focus |
|---|---|
| Application logic | Business rules + error paths (highest priority) |
| Entry points | Mapping + error translation |
| Data access | Query logic + translation correctness |
Documentation (minimum)
Use lightweight, searchable artifacts:
| Artifact | |
|---|---|
| 1 | Contracts (DTOs) documented where they are defined (comments/readme when needed) |
| 2 | Short architecture notes for significant changes (e.g., ADR-style decisions) |
Common Anti-Patterns (Avoid)
| Anti-pattern | Why it hurts | |
|---|---|---|
| 1 | Business logic in entry points | Hard to test, duplicates rules, creates inconsistent behavior |
| 2 | Application logic using DTOs/storage models directly | Boundaries blur; changes ripple across layers |
| 3 | Direct storage access from controllers/handlers | Breaks responsibility boundaries; increases coupling |
| 4 | Implicit contracts (no DTOs) | Integrations break silently; harder reviews and migrations |
| 5 | Logging secrets / raw PII | Security risk and compliance risk |
Asana Card Templates (When Needed)
Use templates when a change crosses boundaries, impacts contracts, or requires explicit review.
Architecture / Contract Change Review
| Asana Card Template | |
|---|---|
| Title | Architecture / contract change review – [System / Feature] |
| Assignee | Technology (owner) |
| Description | Please review the proposed architecture / contract change: Context • System: [System] • Change summary: [What is changing] • Related proposal / delivery context: [Link] Boundary impact • Contracts/DTOs changed: [Yes/No] (list) • External integrations impacted: [Yes/No] (list) • Data storage impacted: [Yes/No] (list) Requested outcome • Confirm responsibility boundaries and data flow • Confirm backward compatibility or migration plan (if needed) • Confirm minimum logging/testing requirements are met When done, add a short decision note and move to In Review. |
Architecture Checklist (Technology Use)
Contracts & boundaries
| Checklist | |
|---|---|
| 1 | ☐ Contracts/DTOs are explicit at boundaries |
| 2 | ☐ Business entities are used only inside application logic |
| 3 | ☐ Storage models stay inside data access |
Data flow & layering
| Checklist | |
|---|---|
| 1 | ☐ Dependency flow is one-way (entry point → application logic → data access) |
| 2 | ☐ Entry points translate DTO ↔ entity |
| 3 | ☐ Data access translates entity ↔ storage/external contracts |
Safety & operability
| Checklist | |
|---|---|
| 1 | ☐ Validation responsibilities are correct (shape at edge, business rules in core) |
| 2 | ☐ Minimum logging present and safe (no secrets/PII) |
| 3 | ☐ Tests cover application logic critical paths |
| 4 | ☐ A short decision note exists for significant changes (ADR-style when needed) |