docs(architecture): add extraction packages section to overview by NTCoding · Pull Request #83 · NTCoding/living-architecture

NTCoding · 2026-01-08T22:11:40Z

User description

Closes #43

Summary

Added comprehensive "Extraction Packages" section to architecture overview documenting the three extraction packages: riviere-extract-config, riviere-extract-conventions, and riviere-extract-ts
Documented dependency relationships between the packages
Explained the enforcement principle: convention without enforcement is unreliable, highlighting ESLint rule support

Test plan

Verify gate passes (lint, typecheck, test)
Review documentation changes in overview.md

🤖 Generated with Claude Code

PR Type

Documentation

Description

Added comprehensive "Extraction Packages" section documenting three TypeScript extraction packages
Documented package dependencies and relationships between config, conventions, and ts packages
Explained enforcement principle: convention requires ESLint rules for deterministic extraction
Clarified how decorators and enforcement ensure reliable architectural component identification

Diagram Walkthrough

flowchart LR
  A["Extraction Packages<br/>Config, Conventions, TS"]
  B["Package Dependencies<br/>Relationships"]
  C["Enforcement Principle<br/>Decorators + ESLint"]
  D["Deterministic<br/>Extraction"]
  A --> B
  A --> C
  C --> D

File Walkthrough

Relevant files

Documentation

overview.md `Add extraction packages documentation and enforcement principle` docs/architecture/overview.md Added new "Extraction Packages" subsection with table describing three packages: riviere-extract-config, riviere-extract-conventions, and riviere-extract-ts Documented package dependency relationships showing how packages depend on config and CLI uses ts extractor Added "Enforcement Principle" subsection explaining why convention requires ESLint enforcement for deterministic extraction Clarified that decorators and ESLint rules ensure all components are annotated and extraction produces consistent results	+36/-0

Summary by CodeRabbit

Documentation
- Updated architecture overview with new Extraction Packages section detailing deterministic TypeScript extraction packages
- Added Package Dependencies subsection documenting dependency relationships among extraction packages
- Added Enforcement Principle subsection explaining component identification consistency mechanisms and enforcement requirements

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add comprehensive documentation of extraction packages (config, conventions, ts) including dependency relationships and enforcement principle. Updates architecture overview to reflect deterministic TypeScript extraction capability. Co-Authored-By: Claude Opus 4.5 <[email protected]>

…te-architecture-ov

coderabbitai · 2026-01-08T22:11:48Z

📝 Walkthrough

Walkthrough

Documentation-only update to the architecture overview introducing three TypeScript extraction packages—riviere-extract-config, riviere-extract-conventions, and riviere-extract-ts—their dependency relationships, and the enforcement principle explaining why decorators and ESLint rules are necessary for deterministic extraction.

Changes

Cohort / File(s)	Summary
Architecture Documentation `docs/architecture/overview.md`	Added "Extraction Packages" section describing three packages for deterministic TypeScript extraction; added "Package Dependencies" subsection documenting relationships among extract-ts, extract-conventions, and CLI; added "Enforcement Principle" subsection explaining why enforcement mechanisms (decorators, ESLint rules) are essential for ensuring consistent, deterministic component extraction.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

feat(riviere-extract): create riviere-extract-conventions package with decorators #59: Implements riviere-extract-conventions package with decorators and enforcement mechanisms that are documented in this PR's new "Enforcement Principle" section
feat(riviere-extract-ts): add TypeScript component extractor #67: Adds @living-architecture/riviere-extract-ts package that is referenced and documented in the new "Extraction Packages" section
docs: add extraction domain terminology to glossary #52: Introduces extraction-domain concepts (config, conventions, enforcement) that align with the architectural documentation added here

Poem

🐰 A rabbit hops through docs so neat,
Extraction packages, what a treat!
Conventions bound with enforcement tight,
Deterministic flows done right! ✨
The architecture now takes flight!

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and concisely describes the main change: adding an extraction packages section to the architecture overview documentation.
Linked Issues check	✅ Passed	The PR fulfills all coding-related objectives from issue #43: documents extraction packages (riviere-extract-config, riviere-extract-conventions, riviere-extract-ts), explains package dependencies, and clearly presents the enforcement principle.
Out of Scope Changes check	✅ Passed	All changes are in-scope documentation updates directly aligned with issue #43 requirements; no unrelated modifications to code or other areas detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c4db0b3 and 38bcff2.

📒 Files selected for processing (1)

docs/architecture/overview.md

🧰 Additional context used

🧠 Learnings (13)

📓 Common learnings

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/architecture/overview.md:0-0
Timestamp: 2026-01-02T17:46:54.167Z
Learning: Applies to docs/architecture/**/*extract*.{js,ts,jsx,tsx} : Extraction code should use the Rivière Builder library to parse code and emit schema components

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/architecture/overview.md:0-0
Timestamp: 2026-01-02T17:46:54.167Z
Learning: Applies to docs/architecture/**/*extract*.{js,ts,jsx,tsx} : Use Rivière Builder library to programmatically build the schema graph when writing extraction code

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Implement extraction logic as pure functions with no side effects

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-config/CLAUDE.md:0-0
Timestamp: 2026-01-06T23:01:34.733Z
Learning: Applies to packages/riviere-extract-config/**/*.ts : Extraction config schema is the source of truth for valid structures. TypeScript types must mirror the schema definition to maintain consistency

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Use ts-morph for TypeScript AST parsing instead of other parsers

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Reject invalid extraction configs at load time, not during extraction phase

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-conventions/CLAUDE.md:0-0
Timestamp: 2026-01-08T07:05:01.746Z
Learning: Applies to packages/riviere-extract-conventions/**/*.ts : Use `Ignore` decorator to exclude classes or methods from architectural extraction analysis

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-conventions/CLAUDE.md:0-0
Timestamp: 2026-01-08T07:05:01.746Z
Learning: Applies to packages/riviere-extract-conventions/**/*.ts : Use `Custom(type)` decorator to annotate components with custom types not covered by standard decorators

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Use glob pattern matching for module-based organization of extraction rules

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-conventions/CLAUDE.md:0-0
Timestamp: 2026-01-08T07:05:01.746Z
Learning: Import and use the default extraction config from `living-architecture/riviere-extract-conventions/default-config` in extraction tooling to detect all 6 component types

📚 Learning: 2026-01-08T17:19:17.122Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Implement extraction logic as pure functions with no side effects

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-02T17:46:54.167Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/architecture/overview.md:0-0
Timestamp: 2026-01-02T17:46:54.167Z
Learning: Applies to docs/architecture/**/*extract*.{js,ts,jsx,tsx} : Extraction code should use the Rivière Builder library to parse code and emit schema components

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-02T17:46:54.167Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/architecture/overview.md:0-0
Timestamp: 2026-01-02T17:46:54.167Z
Learning: Applies to docs/architecture/**/*extract*.{js,ts,jsx,tsx} : Use Rivière Builder library to programmatically build the schema graph when writing extraction code

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-06T23:01:34.733Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-config/CLAUDE.md:0-0
Timestamp: 2026-01-06T23:01:34.733Z
Learning: Applies to packages/riviere-extract-config/**/*.ts : Extraction config schema is the source of truth for valid structures. TypeScript types must mirror the schema definition to maintain consistency

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T17:19:17.122Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Use ts-morph for TypeScript AST parsing instead of other parsers

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T17:19:17.122Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Reject invalid extraction configs at load time, not during extraction phase

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T17:19:17.122Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.{ts,tsx} : Use glob pattern matching for module-based organization of extraction rules

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T07:05:01.746Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-conventions/CLAUDE.md:0-0
Timestamp: 2026-01-08T07:05:01.746Z
Learning: Import and use the default extraction config from `living-architecture/riviere-extract-conventions/default-config` in extraction tooling to detect all 6 component types

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T07:05:01.746Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-conventions/CLAUDE.md:0-0
Timestamp: 2026-01-08T07:05:01.746Z
Learning: Applies to packages/riviere-extract-conventions/**/*.ts : Use `Ignore` decorator to exclude classes or methods from architectural extraction analysis

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T17:19:17.122Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: Applies to packages/riviere-extract-ts/**/*.test.{ts,tsx} : Implement integration tests for end-to-end extraction from TypeScript code to JSON output

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T17:19:17.122Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: packages/riviere-extract-ts/CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:17.122Z
Learning: All extraction rules should come from validated ExtractionConfig provided by riviere-extract-config

Applied to files:

docs/architecture/overview.md

📚 Learning: 2026-01-08T17:19:05.921Z

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-08T17:19:05.921Z
Learning: Extract software architecture from code as living documentation, using Riviere schema for flow-based (not structural) architecture

Applied to files:

docs/architecture/overview.md

🔇 Additional comments (1)

docs/architecture/overview.md (1)

16-51: Extraction Packages section clearly documents the enforcement principle and dependency structure.

The new section effectively addresses all PR objectives: makes enforcement a first-class concept explicit (lines 39–50), visualizes the dependency graph (lines 26–37), and provides sufficient context for developers to understand the extraction architecture. The explanation that "convention without enforcement is unreliable" and the clarification that enforcement ensures determinism is well-articulated. The ESLint rule require-component-decorator is correctly named and properly implemented in the riviere-extract-conventions package.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

qodo-code-review · 2026-01-08T22:11:58Z

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance

🟢

No security concerns identified

No security vulnerabilities detected by AI analysis. Human verification advised for critical code.

Ticket Compliance

🟡

🎫 #43

🟢	Update the architecture overview to include the new extraction packages and their relationships.
	Explain the enforcement philosophy (why config/conventions without enforcement is insufficient for deterministic extraction).
	Make the package dependency structure clear (config used by extract-ts and conventions; CLI uses extract-ts).
	Mention all relevant new extraction packages (riviere-extract-ts, riviere-extract-config, riviere-extract-conventions).
⚪	Ensure the architecture overview enables developers to understand how to use the extraction architecture effectively.

Codebase Duplication Compliance

⚪

Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance

🟢

Generic: Comprehensive Audit Trails

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Meaningful Naming and Self-Documenting Code

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Robust Error Handling and Edge Case Management

Objective: Ensure comprehensive error handling that provides meaningful context and graceful
degradation

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Secure Error Handling

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Secure Logging Practices

Objective: To ensure logs are useful for debugging and auditing without exposing sensitive
information like PII, PHI, or cardholder data.

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Generic: Security-First Input Validation and Data Handling

Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent
vulnerabilities

Status: Passed

Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

cloudflare-workers-and-pages · 2026-01-08T22:12:31Z

Deploying living-architecture with Cloudflare Pages

Latest commit:	`38bcff2`
Status:	✅ Deploy successful!
Preview URL:	https://582f7929.living-architecture.pages.dev
Branch Preview URL:	https://issue-43-m3-d3-4-update-arch.living-architecture.pages.dev

View logs

qodo-code-review · 2026-01-08T22:12:54Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category Suggestion Impact

General

Use consistent package names in documentation

In the package dependency diagram, use the full, scoped package names (e.g.,
@living-architecture/riviere-extract-config) to match the table above it for
consistency.

docs/architecture/overview.md [26-37]

 #### Package Dependencies
 
 ```text
-riviere-extract-ts
-└── uses riviere-extract-config
+@living-architecture/riviere-extract-ts
+└── uses @living-architecture/riviere-extract-config
 
-riviere-extract-conventions
-└── uses riviere-extract-config
+@living-architecture/riviere-extract-conventions
+└── uses @living-architecture/riviere-extract-config
 
 riviere-cli
-└── uses riviere-extract-ts
+└── uses @living-architecture/riviere-extract-ts



- [ ] **Apply / Chat** <!-- /improve --apply_suggestion=0 -->


<details><summary>Suggestion importance[1-10]: 4</summary>

__

Why: The suggestion correctly identifies an inconsistency in package naming within the documentation and proposes a change that improves clarity and consistency for the reader.


</details></details></td><td align=center>Low

</td></tr><tr><td rowspan=1>Possible issue</td>
<td>



<details><summary>Clarify scope of ESLint rule enforcement</summary>

___

**Revise the description of the <code>require-component-decorator</code> ESLint rule to clarify <br>its scope, changing "all classes" to "relevant classes" for better accuracy.**

[docs/architecture/overview.md [46]](https://github.com/NTCoding/living-architecture/pull/83/files#diff-e5a5102f18de6b16b2e09773f0c2fbfadd128b67c023c717ce04f48a940de6caR46-R46)

```diff
-- **ESLint rule** (`require-component-decorator`) to enforce all classes are annotated
+- **ESLint rule** (`require-component-decorator`) to enforce that relevant classes are annotated

Apply / Chat

Suggestion importance[1-10]: 3

__

Why: The suggestion correctly points out that stating the ESLint rule enforces annotation on "all classes" is likely an overstatement. Changing it to "relevant classes" improves the accuracy of the documentation.

Low

More

sonarqubecloud · 2026-01-08T22:13:02Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

NTCoding and others added 2 commits January 8, 2026 22:11

Merge remote-tracking branch 'origin/main' into issue-43-m3-d3-4-upda…

38bcff2

…te-architecture-ov

qodo-code-review Bot added the Review effort 2/5 label Jan 8, 2026

coderabbitai Bot approved these changes Jan 8, 2026

View reviewed changes

NTCoding merged commit c0c3af9 into main Jan 8, 2026
18 checks passed

This was referenced Jan 9, 2026

docs: update CLAUDE.md with riviere-extract-config dependencies #87

Merged

docs(extraction): add comprehensive deterministic extraction docs #130

Merged

docs(prd): improve Phase 11 Metadata Extraction PRD based on review feedback #162

Merged

This was referenced Jan 28, 2026

chore: folder structure ADRs #213

Merged

docs(extract): add extraction rules reference, metadata enrichment, and AI scanner prompt #245

Merged

Navigation Menu

Repository navigation

docs(architecture): add extraction packages section to overview - #83

docs(architecture): add extraction packages section to overview#83
NTCoding merged 2 commits into
mainfrom
issue-43-m3-d3-4-update-architecture-ov

NTCoding commented Jan 8, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jan 8, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

qodo-code-review Bot commented Jan 8, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Jan 8, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot commented Jan 8, 2026

Uh oh!

sonarqubecloud Bot commented Jan 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

NTCoding commented Jan 8, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Summary

Test plan

PR Type

Description

Diagram Walkthrough

File Walkthrough

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

qodo-code-review Bot commented Jan 8, 2026

PR Compliance Guide 🔍

Uh oh!

cloudflare-workers-and-pages Bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying living-architecture with Cloudflare Pages

Uh oh!

qodo-code-review Bot commented Jan 8, 2026

PR Code Suggestions ✨

Uh oh!

sonarqubecloud Bot commented Jan 8, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

NTCoding commented Jan 8, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jan 8, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jan 8, 2026 •

edited

Loading