# Pre Build Architect

> 6-layer pre-code architecture mapping skill. Use before writing any non-trivial implementation to map the full architectural surface before the first line of code. Triggers on "architect this", "map the architecture", "design before build", or automatically when spec-architect Phase 2 involves cross-system impact. Outputs a layered architecture map that feeds into DECISIONS.md.

- Skill: `arogyareddy/pre-build-architect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arogyareddy/pre-build-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arogyareddy/pre-build-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: arogyareddy (https://skillmd.com/u/arogyareddy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arogyareddy/pre-build-architect

---


# Pre-Build Architect Skill

## Purpose

Before implementation, map the 6 architectural layers the change touches.
This prevents mid-build discovery of integration conflicts, missing abstractions,
and design decisions that should have been made before any code existed.

"An hour of architecture saves a day of refactoring."

## The 6 Layers

### Layer 1 — Data Layer
- What entities are involved? (tables, collections, models)
- What columns / fields change? (add, modify, remove)
- What indexes are needed? (new queries = new indexes)
- What constraints apply? (nullable, unique, foreign key, check)
- Migration: is this forward-compatible? Can it be rolled back?

### Layer 2 — Repository / Data Access Layer
- What queries does this feature require?
- Are they covered by existing repository methods or do new ones need creating?
- Any N+1 risks in how data will be fetched?
- Transaction boundaries: what must succeed or fail atomically?

### Layer 3 — Business Logic / Service Layer
- What business rules govern this feature?
- Which service owns this logic? (one owner, not split across services)
- What are the invariants? (conditions that must always be true after this runs)
- What domain events does this trigger?
- For payroll: where do accumulators, thresholds, and compliance checks live?

### Layer 4 — API / Interface Layer
- What endpoints are needed? (method, path, auth level)
- What is the request contract? (typed schema)
- What is the response contract? (typed schema, including all error responses)
- What validation happens at this layer vs the business layer?
- Versioning: does this break existing consumers?

### Layer 5 — Integration Layer
- What external systems are called? (APIs, queues, file systems, webhooks)
- What are the failure modes? (timeout, rate limit, partial response)
- Are calls idempotent? (what happens on retry?)
- What data crosses trust boundaries? (PII, financial, secrets)

### Layer 6 — Observability Layer
- What logs are needed to debug a production failure of this feature?
- What metrics track its health? (success rate, latency, error rate)
- What audit events are required? (compliance, who/when/what on every write)
- What alerts should fire? (payroll: amounts outside expected range, run failures)

## Output Format

```
## Architecture Map — [Feature Name]

Layer 1 (Data):
  Entities affected: [list]
  Schema changes: [column, type, nullable, index]
  Migration reversible: yes / no

Layer 2 (Repository):
  New methods needed: [list]
  Existing methods reused: [list]
  Transaction boundary: [description]

Layer 3 (Service):
  Owner service: [name]
  Business rules: [list]
  Invariants guaranteed: [list]

Layer 4 (API):
  Endpoints: [METHOD /path — auth level]
  Request type: [reference]
  Response type: [reference]

Layer 5 (Integration):
  External calls: [list / none]
  Failure strategy: [retry / fail-fast / fallback]

Layer 6 (Observability):
  Logs: [what, what level]
  Audit events: [list / none]
  Alerts: [trigger conditions]

Architecture risks: [top 1-2]
Decision required: [any conflict needing human input]
```

Log this map to DECISIONS.md before implementation begins.