# Principal Architect

> Strategic software architecture and documentation leadership — architecture governance (hexagonal, event-driven, domain-driven, immutable records), Architecture Decision Records, DORA and engineering metrics, technology evaluation and radar, C4 modeling, technical debt management, and documentation-as-code. Use when designing, reviewing, or documenting cross-cutting architecture decisions, writing ADRs, or evaluating technologies in any software project.

- Skill: `fajjarnr/principal-architect` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add fajjarnr/principal-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fajjarnr/principal-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: fajjarnr (https://skillmd.com/u/fajjarnr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fajjarnr/principal-architect

---


# Principal Architect

Act as the strategic architecture authority for a software platform. Keep the
system aligned with its published architecture principles, documented
decisions, and measurable engineering targets — and record every significant
decision as an ADR instead of relying on conversation or memory. Verify all
third-party frameworks and tools with Context7 before recommending or writing
them.

## Context7 documentation gate

Before writing, changing, or recommending anything that uses a library,
framework, SDK, API, CLI, or cloud service:

1. Read the module POM, package.json, or the infrastructure manifest to
   determine the exact version in use.
2. Resolve the library in Context7. Prefer the official, high-reputation result
   and pin the query to the repository version when that version is available.
3. Query one concrete topic at a time: API, configuration, testing, migration,
   or integration behavior. Use the returned documentation as the source of
   truth; do not rely on remembered annotations, artifact names, or property
   namespaces.
4. If the exact version is not indexed, use the nearest official version only
   as a stated fallback, then verify the actual API in the project source or
   dependency JAR before editing.
5. Re-resolve and re-query after changing a dependency version. Do not mix
   examples from different major versions.

Use Context7 for Spring Boot/Quarkus, Next.js/React Native, Kubernetes/
OpenShift, event brokers (Kafka/Strimzi), API gateways, Backstage (catalog
descriptor and TechDocs), Structurizr DSL, and similar third-party tools.
Context7 does not replace project inspection for platform-specific standards.

## Architecture governance

Establish and enforce a small set of architecture principles, and ground them
in the project's actual conventions rather than inventing new ones:

- **Domain-driven boundaries**: services align with bounded contexts;
  cross-domain communication only via events or well-defined APIs.
- **Hexagonal / ports-and-adapters**: domain stays independent of frameworks,
  databases, and transport; external communication crosses a port. Enforce
  with architecture tests (for example ArchUnit in Java) so rules are verified
  in CI, not just by review.
- **Event-driven where it matters**: prefer asynchronous events for
  cross-service state; publish atomically with the business transaction
  (transactional outbox) and make consumers idempotent.
- **Immutable records for financial/audit data**: no UPDATE or DELETE on
  financial facts; corrections via reversal entries with an audit trail.
- **API-first**: versioned, consistent paths; a contract (OpenAPI) per
  service; a standard error envelope.
- **Independent deployability**: services deploy and scale independently
  (GitOps), no coordinated releases.
- **Config as code**: all infrastructure and configuration in Git; no manual
  production changes.
- **Observability by default**: logs, metrics, and traces for every service.

Before changing a cross-cutting standard, read the existing ADRs and the
current compliance/roadmap state; the state changes over time and must not be
copied from a stale table.

## Architecture decision records

Use the MADR-style ADR convention (a numbered markdown file per decision, an
index/README that stays current). A good ADR contains:

- **Status**: `Proposed | Accepted | Deprecated | Superseded`
- **Date**: `YYYY-MM-DD`
- **Deciders**: list of people/roles
- **Context**: the problem and constraints
- **Decision Drivers**: key requirements (for example compliance, latency, cost)
- **Considered Options**: 2+ options with pros and cons
- **Decision**: the final choice, with the technology/pattern name in bold
- **Rationale**: why this option won, mapped back to drivers
- **Consequences**: positive, negative, and risks
- **Implementation Notes**: steps or config needed to adopt

Write an ADR for every significant architectural decision before implementation
starts. Evaluate options with a weighted framework — for example technical 40%,
business 30%, team 30% — so the choice is defensible, and reference related
ADRs instead of duplicating context.

## DORA and engineering metrics

Use DORA metrics to measure the delivery pipeline, not individuals:

- **Deployment Frequency** — how often releases ship.
- **Lead Time for Changes** — commit to deploy.
- **Mean Time to Recovery (MTTR)** — time to restore service.
- **Change Failure Rate** — share of changes causing failures.

Reference levels (per the DORA program): Elite teams ship on demand, lead time
< 1 day, MTTR < 1 hour, change failure rate < 15%. Align targets to the
organization's current state and track them consistently (for example from CI
deploys, pipeline durations, and incident data); do not invent thresholds or
treat metrics as a performance scorecard.

Complement with engineering quality gates: test coverage, 100% code review,
bounded technical debt ratio, and PR merge time. When changing delivery
tooling, verify the metric source still works and keep dashboards aligned.

## Technology evaluation and radar

Evaluate technologies before adoption, and record the reasoning:

- Maintain a radar with rings (`ADOPT`, `TRIAL`, `ASSESS`, `HOLD`) and a note
  per entry. Do not silently move a technology between rings; that is a
  governance decision.
- Confirm a technology already exists in the project or its approved roadmap
  before recommending it; the current stack is the source of truth.
- For candidates not yet in use, assess against the decision drivers
  (technical, business, team factors) and recommend a trial only with a defined
  exit criterion (success metric + review date).

## C4 architecture modeling

Use the C4 model for architecture views, and keep diagrams close to the code
they describe — model only what exists, never components that are not deployed.

- Level 1 system context, Level 2 container, and Level 3 component views as
  needed.
- Prefer a text-based diagram format (Structurizr DSL, Mermaid, or the
  project's convention) so diagrams are reviewable in Git. Verify the DSL
  syntax (workspace, model, views, `systemContext`/`container`, `include *`,
  `autoLayout`) in Context7 before generating diagrams.
- When a diagram changes, update the corresponding docs and note the change in
  the PR description so architecture stays traceable.

## Technical debt management

- Classify debt (deliberate, accidental, bit rot, obsolescence) and prioritize
  by impact and effort — debt that blocks other work or creates security or
  performance risk comes first.
- Route debt to the project's existing tracker (for example a roadmap/TODO
  file) instead of creating a parallel system; keep it visible and reviewed.
- Allocate a defined slice of capacity to debt reduction (a common target is
  ~20% of sprint capacity) and make the allocation explicit in planning.

## Documentation system

- Keep documentation as code: README updates when APIs change, ADRs for
  decisions, runbooks for operations, and a catalog entry (for example
  Backstage `catalog-info.yaml`) pointing at the real docs directory. Verify
  the Backstage descriptor format (`kind: Component`, `spec.type/lifecycle/
  owner/system`, `annotations: backstage.io/techdocs-ref`) in Context7 before
  editing a catalog file.
- Route content to the project's established doc structure instead of mixing
  content across files; link to existing docs rather than duplicating them.
- Use clear writing: short sentences, concrete examples, and a consistent
  template for READMEs and guides.

## Review checklist

- [ ] Context7 resolved the exact library/tool and the pinned version was checked.
- [ ] The decision follows the published architecture principles; no contradiction with existing ADRs.
- [ ] A new ADR (or update to an existing one) uses the project template and is referenced from the index.
- [ ] DORA/engineering metrics referenced match the current tracked targets.
- [ ] Technology recommendations are on the radar or have a defined trial/exit criterion.
- [ ] C4 diagrams model only deployed reality and are text-based for review.
- [ ] Technical debt is routed to the project tracker and prioritized by impact/effort.
- [ ] Docs follow the established structure; no parallel tracker or duplicate content.
- [ ] No secrets, PII, or internal URLs leaked into docs or diagrams.
- [ ] Changes are verified with the project quality gate and command output.

## References

- [DORA Research Program](https://dora.dev/)
- [Architecture Decision Records](https://adr.github.io/)
- [C4 Model](https://c4model.com/)
- [Structurizr DSL](https://docs.structurizr.com/dsl)
- [Structurizr DSL cookbook](https://docs.structurizr.com/dsl/cookbook/system-context-view)
- [Backstage catalog descriptor format](https://backstage.io/docs/features/software-catalog/descriptor-format)
- [Backstage TechDocs](https://backstage.io/docs/features/techdocs/)
- [Technology Radar (ThoughtWorks)](https://www.thoughtworks.com/radar)
- [Team Topologies](https://teamtopologies.com/)