Part 4: Adding Richness Layer by Layer

In Part 3 you created a working annotation with 4 tags. Now you will layer in architecture, enrichment, and shape extraction tags — each group unlocks new documentation capabilities.

4.1 Add architecture tags

Add these three tags to the JSDoc block in user-service.ts, after @libar-docs-brief:

 * @libar-docs-arch-role service
 * @libar-docs-arch-context identity
 * @libar-docs-arch-layer application

Architecture tags place your pattern in a structured topology:

Tag	Example	Purpose
@libar-docs-arch-role	service	Component type: service, infrastructure, etc.
@libar-docs-arch-context	identity	Bounded context (creates diagram subgraphs)
@libar-docs-arch-layer	application	Architecture layer: domain, application, infrastructure

Run npm run process:tags to see architecture metadata in the tag usage report:

npm run process:tags

{
  "success": true,
  "data": {
    "tags": [
      { "tag": "status", "count": 1, "values": [{ "value": "active", "count": 1 }] },
      { "tag": "category", "count": 1, "values": [{ "value": "core", "count": 1 }] },
      { "tag": "arch-role", "count": 1, "values": [{ "value": "service", "count": 1 }] },
      { "tag": "arch-context", "count": 1, "values": [{ "value": "identity", "count": 1 }] },
      { "tag": "arch-layer", "count": 1, "values": [{ "value": "application", "count": 1 }] }
    ],
    "patternCount": 1
  }
}

What just happened: Architecture tags tell the system where this component lives in your system topology. These drive the Mermaid diagrams generated later — bounded contexts become subgraphs, roles become node labels.

4.2 Add enrichment tags

Add these tags to user-service.ts:

 * @libar-docs-usecase "Register a new user account via the signup form"
 * @libar-docs-usecase "Look up a user by ID for profile display"
 * @libar-docs-usecase "Deactivate a compromised user account"
 * @libar-docs-quarter Q1-2026
 * @libar-docs-phase 1
 * @libar-docs-release v0.1.0

Tag	Example	Purpose
@libar-docs-usecase	"Register a new user..."	Use cases (quoted, repeatable)
@libar-docs-quarter	Q1-2026	Timeline tracking
@libar-docs-phase	1	Roadmap phase number
@libar-docs-release	v0.1.0	Target release version

npm run process:overview

=== PROGRESS ===
1 patterns (0 completed, 1 active, 0 planned) = 0%

=== ACTIVE PHASES ===
Phase 1: Inception (1 active)

What just happened: The @libar-docs-phase 1 tag assigns UserService to Phase 1. Phase names like “Inception” come from the 6-phase-standard workflow built into the preset. The six phases are: Inception, Elaboration, Session, Construction, Validation, Retrospective.

4.3 Add shape extraction

Shape extraction pulls TypeScript interfaces into your generated docs. Add this tag to the pattern’s JSDoc block:

 * @libar-docs-extract-shapes UserRecord

Then add the interface above the class, with its own shape tag:

/** @libar-docs-shape reference-sample */
export interface UserRecord {
  id: string;
  email: string;
  active: boolean;
}

Tag	Example	Purpose
@libar-docs-extract-shapes	UserRecord	Extract named TypeScript types into docs
@libar-docs-shape	reference-sample	Mark an interface for shape discovery (optional group name)

npm run process:overview

=== PROGRESS ===
2 patterns (0 completed, 1 active, 1 planned) = 0%

=== ACTIVE PHASES ===
Phase 1: Inception (1 active)

The pattern count increased from 1 to 2 — UserRecord now appears as a separate shape pattern in the registry.

Note: @libar-docs-shape on an interface creates a lightweight “Shape” entry. The linter will flag these for missing @libar-docs-pattern names, which is expected and harmless.

4.4 Full tag reference

Here is the complete tag reference for TypeScript annotations. You have now used every group:

Identity & Status:

Tag	Example	Purpose
@libar-docs-pattern	UserService	Names this pattern (required)
@libar-docs-status	active	FSM status: roadmap -> active -> completed, or deferred
@libar-docs-core	(flag)	Category assignment. Also: @libar-docs-api, @libar-docs-infra

Architecture:

Tag	Example	Purpose
@libar-docs-arch-role	service	Component type
@libar-docs-arch-context	identity	Bounded context
@libar-docs-arch-layer	application	Architecture layer

Enrichment:

Tag	Example	Purpose
@libar-docs-brief	Core user lifecycle...	Short description for summary tables
@libar-docs-usecase	"Register a new user..."	Use cases (quoted, repeatable)
@libar-docs-quarter	Q1-2026	Timeline tracking
@libar-docs-phase	1	Roadmap phase number
@libar-docs-release	v0.1.0	Target release version

Shapes:

Tag	Example	Purpose
@libar-docs-extract-shapes	UserRecord	Extract named types into docs
@libar-docs-shape	reference-sample	Mark an interface for shape discovery

Checkpoint: Part 4

• user-service.ts has architecture tags (arch-role, arch-context, arch-layer)
• user-service.ts has enrichment tags (usecase, quarter, phase, release)
• user-service.ts has shape extraction (extract-shapes + @libar-docs-shape on interface)
• npm run process:overview shows “Phase 1: Inception”

Recap: Part 4

Starting from 4 tags, you added three groups:

• Architecture tags — role, context, layer -> drive Mermaid diagrams
• Enrichment tags — use cases, timeline, release -> drive roadmaps and detail pages
• Shape extraction — TypeScript interfaces become API type documentation

Your single file now carries enough metadata to generate rich, multi-format documentation.

---