tomevault-io Architecture Audit Procedure
Invoke with /tzurot-arch-audit to audit codebase architecture and health.
Run this periodically (before PRs, start of session, after major changes) to catch boundary violations, dead code, duplication, and coverage gaps.
Standards live in .claude/rules/01-architecture.md. Rationale in docs/reference/STATIC_ANALYSIS.md. This skill is the verification procedure.
Quick Scan
Fast triage (~30 seconds). Run frequently — before PRs or at session start.
pnpm ops xray --summary # Package health warnings
pnpm ops xray --suppressions # Suppression audit (tech debt)
pnpm depcruise # Boundary violations vs baseline
pnpm ops test:audit # Coverage ratchet status
If all green (no new warnings, violations, or gaps): stop here.
If anything flags: proceed to the relevant Deep Dive section below.
Deep Dive
Work through each section that the quick scan flagged, or run all 7 periodically.
1. Service Boundaries
Tool: pnpm depcruise
What it catches:
- Prisma imports in bot-client (error)
- Cross-service direct imports (error)
- Circular dependency chains (error)
- ai-worker importing Discord.js directly (warn)
Interpreting results:
pnpm depcruise # Shows NEW violations beyond baseline
pnpm depcruise:baseline # Update baseline after fixing violations
| Result | Meaning | Action |
|---|---|---|
0 new violations |
Clean | None |
New error severity |
Boundary broken | Fix now — move shared code to common-types or use API calls |
New warn severity |
Soft boundary | Track — add to backlog if pattern is spreading |
| Baseline count decreased | Progress | Run pnpm depcruise:baseline to lock in improvement |
Current baseline: 54 circular dependency violations (pre-existing). New circular deps beyond baseline are flagged.
Reference: .dependency-cruiser.cjs for rule definitions, .dependency-cruiser-baseline.json for known violations.
2. Package Health
Tool: pnpm ops xray --summary
What it catches:
- Files approaching or exceeding 400/500 line limits
- Packages exceeding 3000 total lines or 50+ exports
- ESLint suppression clusters (>20 suppressions in one file)
Interpreting results:
| Warning | Threshold | Action |
|---|---|---|
| File >400 lines | 400 warn, 500 error | Fix now if >500 (ESLint blocks). Track if 400-500. |
| Package >3000 lines | 3000 | Track — consider splitting. Watch common-types especially. |
| Package >50 exports | 50 | Track — sign of bloated API surface. |
| Suppression cluster >20 | 20 | Track — file may need refactoring instead of suppressing. |
Deeper investigation:
pnpm ops xray <package-name> # Full declarations for one package
pnpm ops xray --include-private # Include non-exported declarations
3. Suppression Audit
Tool: pnpm ops xray --suppressions
What it catches:
- Lint/type suppressions without justification comments
- Rules suppressed most frequently (potential systemic issues)
- Packages with highest suppression density
- "pre-existing" tech debt vs intentional suppressions
Interpreting results:
| Finding | Action |
|---|---|
| No justification suppressions | Fix now — add -- reason or fix the underlying issue |
| High count for a single rule | Track — may indicate a systemic issue needing refactoring |
| "pre-existing" dominates | Track — chip away during related changes |
| Single file with many supprs | Track — file may need refactoring instead of suppressing |
Single package audit:
pnpm ops xray bot-client --suppressions # Audit one package
4. Dead Code
Tool: pnpm knip
What it catches:
- Unused exported functions, types, constants
- Files not imported by any entry point
- Dependencies in package.json not used in code
- Unlisted dependencies (used but not declared)
Interpreting results:
| Finding | Action |
|---|---|
| Unused export in service code | Fix now — remove the export |
| Unused export in common-types | Verify not used at runtime (check all services). If truly unused, remove. |
| Unused dependency | Fix now — pnpm remove <dep> from the relevant package |
| Unlisted dependency | Fix now — pnpm add <dep> to the relevant package |
| False positive (runtime-only usage) | Accept — add to knip.json ignore |
Auto-fix (review diff before committing):
pnpm knip:fix # Removes unused exports
5. Code Duplication
Tool: pnpm cpd
What it catches:
- Copy-pasted code blocks across files
- Total duplication percentage vs 5% threshold
Interpreting results:
pnpm cpd # Console output
pnpm cpd:report # HTML report in reports/jscpd/
| Finding | Action |
|---|---|
| Cross-service duplication | Fix now — extract to common-types |
| Within-service duplication | Track — extract helper if >3 occurrences |
| Total >5% | Fix now — CI will fail |
| Test file duplication | Accept — tests are excluded from CPD |
Suppressing intentional duplication:
/* jscpd:ignore-start */
// Reason: <explain why duplication is intentional>
/* jscpd:ignore-end */
6. Test Coverage
Tool: pnpm ops test:audit
What it catches:
- New API schemas without corresponding tests
- New Prisma services without test coverage
- Coverage gaps below 80% threshold
Interpreting results:
pnpm ops test:audit # Check current state vs baseline
pnpm ops test:audit --update # Update baseline after closing gaps
| Finding | Action |
|---|---|
| "NEW gaps found" | Fix now — write tests, never add to knownGaps |
Existing knownGaps items |
Track — chip away at tech debt |
| Coverage below 80% | Fix now — Codecov blocks PRs |
Baseline file: .github/baselines/test-coverage-baseline.json
Critical rule: Never add new code to knownGaps. That baseline is for pre-existing tech debt only.
7. Full Structure Review
Tool: pnpm ops xray --format md
When: Periodically (monthly or after major feature work), not every session.
What to look for:
pnpm ops xray --format md # Full markdown report
pnpm ops xray --format md --imports # Include import analysis
pnpm ops xray --summary --output f # Write summary to file for diffing
| Pattern | What it suggests |
|---|---|
| One package dwarfs others | Extraction candidate — is it doing too much? |
| Package with 0 exports | Dead package or missing entry point |
| High import fan-in on one file | Potential god-module, consider splitting |
| common-types >50 exports | Bloat — extract domain-specific packages |
| Circular import patterns | Architectural coupling — may need interface extraction |
Findings Template
Use this format to report audit results:
## Architecture Audit — YYYY-MM-DD
### Metrics
| Metric | Current | Baseline | Trend |
| ---------------- | ------- | -------- | ----- |
| Circular deps | NN | 54 | +/-N |
| CPD % | N.N% | 5% max | +/-N |
| Knip findings | NN | — | — |
| Coverage gaps | NN | NN | +/-N |
| Files >400 lines | NN | — | — |
### Fix Now
- [ ] Item (tool that flagged it)
### Track (add to BACKLOG.md)
- [ ] Item (current value → target)
### Accepted (reviewed, intentional)
- Item (reason)
After Audit
- Fix "Fix Now" items immediately
- Update baselines to lock in improvements:
pnpm depcruise:baseline # If circular deps decreased pnpm ops test:audit --update # If coverage gaps closed - Add "Track" items to
BACKLOG.mdInbox - Commit:
docs: architecture audit YYYY-MM-DDorfix: address architecture audit findings
References
- Architecture rules:
.claude/rules/01-architecture.md - Static analysis rationale:
docs/reference/STATIC_ANALYSIS.md - Test coverage baseline:
.github/baselines/test-coverage-baseline.json - Dependency cruiser config:
.dependency-cruiser.cjs - Dependency cruiser baseline:
.dependency-cruiser-baseline.json - Knip config:
knip.json - CPD config:
.jscpd.json
Converted and distributed by TomeVault — claim your Tome and manage your conversions.