Semantic comparison of content in technical-documentation/contents/ against
documentation/src/content/docs/ to identify topics that have not been
migrated or that lost significant depth during migration.
Both content trees were inventoried file-by-file (231 files in
technical-documentation, 506+ in documentation). Each topic was compared on
three axes:
- Existence — Is there a page in the documentation site that addresses the
same concept?
- Depth — Does the documentation site match the level of detail
(explanations, decision rationale, edge cases)?
- Diagrams — Are visual artifacts (PlantUML, DrawIO SVG, PNG mockups)
present or have they been lost?
Status legend used throughout:
| Status | Meaning |
|---|
| Missing | No equivalent content exists in the documentation site |
| Partial | Topic exists but with significantly less depth, missing diagrams, or scattered across files without consolidation |
| Covered | Adequately represented; may differ in structure but semantically equivalent |
The documentation site covers the majority of the technical-documentation
content, often in a better-organized form. However, several categories of
content were not migrated:
- 3 topics were missing entirely — all now resolved (M-1, M-4, M-5).
- 12 topics were partially covered — all now resolved (P-1 through P-12).
- 2 topics previously flagged as missing were reclassified — the source
files were stubs with no substantive content, and the documentation site’s
GEN domain already provides far more comprehensive coverage of the same
patterns.
- The remaining ~95% of topics were already covered — often with improved structure.
All identified gaps have been addressed. The resolutions involved:
- New pages created (8): product areas overview, vision functional, viewpoint mapping, bulk operations feature, kanban notes feature, DA endpoint guide, DA API guide, DA limitations.
- Existing pages expanded (6): oauth2-drafts, kanban-cards-module, build-and-deployment, purchase-order-feature, gradle-project-setup, pdf-printing.
- Diagrams migrated (13 files): 6 DrawIO SVGs, 4 Gradle PNGs, 3 demo layout PNGs — all linked from their target pages.
- Already resolved on verification (2): PO implementation notes exceeded source depth; PO UI requirements already integrated.
These topics exist in technical-documentation with substantive content but have
no equivalent page in the documentation site.
| |
|---|
| Source | 1_specifications/general/index.md |
| Resolution | Created product/index.md with the three-area strategic framing (Core Platform, Manufacturing & Material Flow, Business & Supply Chain), mapped to the 12 functional domains with links to use cases, features, and personas. Current capabilities are described inline; aspirational capabilities (production management, quality, asset maintenance, fulfillment, advanced planning, shop-floor integration, multi-site operations) are placed in vision/functional/index.md. |
| Files created | product/index.md (current-state overview + domain mapping), vision/functional/index.md (full aspirational capability set) |
| |
|---|
| Source | 1_specifications/general/ux/capture/index.md, 1_specifications/general/ux/scanning/index.md |
| Finding | Both source files are stubs containing only “To be added” — no substantive specification was ever written. The documentation site’s GEN domain provides far more comprehensive coverage of the underlying patterns: GEN::ENT-DA covers form-based data capture (creation, editing, validation, auto-save), GEN::MEDIA covers multi-method input detection (file, drag-drop, clipboard, URL, camera), and product/publications/scanning-cards.md covers QR scanning interaction. |
| Status | No migration needed. The source had no content to migrate. |
| |
|---|
| Source | 1_specifications/general/ux/workflow-elements/index.md |
| Finding | Source file is a stub containing only “To be added” — no specification was ever written. The documentation site’s GEN domain partially covers workflow elements through GEN::INT (cancel/undo flows) and GEN::ENT-DA (detail panel as workflow hub with action buttons). Wizard/multi-step workflow patterns and progress indicators remain unspecified in both the source and the documentation site, but this is a new specification gap, not a migration gap. |
| Status | No migration needed. The source had no content to migrate. |
| |
|---|
| Source | 2_design/2_functional/general/module-design/api/data-authority-endpoint-implementation.md |
| Resolution | Created process/craft/implementation/data-authority-endpoint-guide.md — an 8-step procedural guide covering payload/metadata definition, table/record mapping, validator, universe, service, endpoint (with reify factory), Ktor module wiring, and Flyway migration. All code examples verified against current common-module implementation. Includes a completion checklist. |
| Files created | process/craft/implementation/data-authority-endpoint-guide.md |
| |
|---|
| Source | 2_design/2_functional/general/module-design/api/data-authority-limitations.md |
| Resolution | Created current-system/architecture/data-authority-limitations.md. Verified all 8 limitations against current common-module implementation: 3 resolved (page tokens, OR/NOT filters, page token validation), 2 partially addressed (query validation, aggregation, sorting), 3 still limited (full-text search, field projections, aggregation API exposure). Includes resolved section documenting what was fixed and potential enhancements table. |
| Files created | current-system/architecture/data-authority-limitations.md |
These topics have some representation in the documentation site but with
significant depth, diagram, or consolidation gaps.
| |
|---|
| Source | 2_design/2_functional/general/module-design/OAuth2/misc-drafts/ (5 files: token-limits, signup, token-exchange, token-augmentation, separate-claims-server) |
| Documentation site | current-system/functional/authentication/oauth2-drafts.md |
| Gap | The documentation site summarizes the concepts (token size, exchange flow, separate auth service recommendation) but does not preserve the per-alternative analysis: trade-offs evaluated, why alternatives were rejected, and the decision trail. |
| Recommendation | Expand oauth2-drafts.md or add a decision record in decisions/record/. |
| |
|---|
| Source | 2_design/viewpoint-mapping.md |
| Documentation site | current-system/architecture/design-framework.md describes viewpoints; no systematic cross-reference. |
| Gap | The original document provides an explicit mapping table from functional areas/modules to source repositories and code paths. The documentation site describes the viewpoints conceptually but does not provide this navigation aid. |
| Recommendation | Add to current-system/architecture/ or link from design-framework.md. |
| |
|---|
| Source | 1_specifications/mvp2/bulk-operations/ (index.md, requirements.md) |
| Documentation site | Bulk operations appear in individual use case scenarios (e.g., row selection for bulk delete in GEN::ENT-DA) but are not consolidated. |
| Gap | No unified specification for bulk behaviors: selection models, batch size limits, progress reporting, partial failure handling, undo semantics. Individual use cases reference bulk actions without defining the shared contract. |
| Recommendation | Create product/use-cases/general-behaviors/bulk-operations.md. |
| |
|---|
| Source | 2_design/2_functional/module-structure/resources/kanban-cards/kanban-qr-code.md |
| Documentation site | current-system/functional/resources/kanban-cards-module.md has the QR URL format; product/publications/scanning-cards.md has user-facing scanning guidance. |
| Gap | Technical QR specification missing: encoding format, QR version, error correction level, minimum print size, label placement guidelines. The functional URL is documented but the physical artifact spec is not. |
| Recommendation | Expand kanban-cards-module.md or add to product/features/. |
| |
|---|
| Source | 2_design/2_functional/module-structure/resources/kanban-cards/kanban-notes.md |
| Documentation site | Kanban card state machine is well-documented; notes/annotations feature is not mentioned. |
| Gap | The ability to attach notes or annotations to kanban cards (timestamped remarks, operator observations) is specified in design but absent from the documentation site’s kanban coverage. |
| Recommendation | Add to current-system/functional/resources/kanban-cards-module.md or product/use-cases/resources/kanban-cards.md. |
| |
|---|
| Source | Multiple SVG diagrams: context.drawio.svg, functional-tld.drawio.svg, module-structure.drawio.svg, dns-structure.drawio.svg, http-network.drawio.svg, mtls-aws-architecture.drawio.svg |
| Resolution | Migrated 6 SVGs to _assets/ subdirectories and linked from their respective pages: context/system-context.md, functional/index.md, architecture/data-authority-pattern.md, runtime/dns-structure.md, runtime/network-routing.md, runtime/mtls.md. |
| |
|---|
| Source | 5_craft/assets/gradle-project/ — 4 PNG diagrams |
| Resolution | Migrated all 4 PNGs to process/craft/implementation/_assets/ and linked from gradle-project-setup.md in the CI/CD and Deployment Approval sections. |
| |
|---|
| Source | 2_design/2_functional/demo202509/assets/ — label-layout.png, breadcrumb-layout.png, card-layout.png |
| Resolution | Migrated all 3 PNGs to current-system/functional/demo-specifics/_assets/ and linked from pdf-printing.md under each layout-specific schema section. |
| |
|---|
| Source | 1_specifications/mvp2/purchase-orders/ui-requirements.md |
| Resolution | The UI structure was already integrated into current-system/functional/procurement/order-implementation-notes.md during a prior migration. Added a UI Structure section to product/features/purchase-order-feature.md summarizing the four view types (list, detail, editor, lookup) with cross-links to the implementation notes. |
| |
|---|
| Source | 1_specifications/mvp2/purchase-orders/implementation-notes.md (42 lines) |
| Resolution | Verified: the documentation site’s order-implementation-notes.md (332 lines) is a significantly expanded version that integrates both the source implementation notes AND the UI requirements. Includes data model changes, UI structure diagrams, update propagation rules, and an information model dependency PlantUML diagram. No action needed — the target exceeds the source in depth. |
| |
|---|
| Source | 2_design/development-pipelines.md |
| Documentation site | current-system/runtime/development-pipelines.md and current-system/runtime/build-and-deployment.md |
| Gap | The original treats pipelines as an architectural concern (how pipelines compose, what guarantees they provide, how they relate to the artifact viewpoint). The documentation site versions are more operational (how to run them). The design rationale and architectural framing is thinner. |
| Recommendation | Enrich build-and-deployment.md with architectural rationale from the original. |
| |
|---|
| Source | 2_design/2_functional/general/module-design/api/data-authority-endpoint-use.md |
| Documentation site | current-system/architecture/api-design.md covers URL patterns and filtering. current-system/functional/api-endpoint-catalog.md lists endpoints. |
| Gap | The original is a consumer-oriented guide: how to call Data Authority endpoints, what headers to send, how to interpret responses, pagination cursors, and filtering examples. The documentation site has the design-side view but not the consumer-side cookbook. |
| Recommendation | Add to current-system/architecture/ or process/craft/implementation/. |
For completeness, these are topics that were fully migrated despite significant
complexity. No action needed.
| Technical-Documentation Topic | Documentation Site Location | Notes |
|---|
| Bitemporal persistence | current-system/architecture/persistence/bitemporal-persistence.md | Full depth preserved |
| Entity model (meta layer) | domain/information-model/meta/entities.md | Expanded with entity-references.md |
| Query DSL with JSON examples | current-system/architecture/query-dsl.md | Comprehensive including JSON formats |
| Item mutation intent (LAX/STRICT/PROPAGATE) | domain/information-model/transactions/item-mutation.md | Complete specification |
| Universe design | current-system/architecture/persistence/universe-design.md | Full interface and validation layers |
| Table mappings guide | current-system/architecture/persistence/table-mappings.md | Step-by-step implementation reference |
| DBIO pattern | current-system/architecture/functional-programming.md | IO Monad section with code examples |
| Ktor module wiring | current-system/architecture/implementation-patterns.md | Canonical Module.kt structure |
| Cedar authorization | technology/cedar-authorization.md | Comprehensive with examples |
| Cognito service design | current-system/functional/system/security/cognito-service.md | Component diagram preserved |
| Customer acquisition channels | current-system/functional/system/customer-acquisition.md | Workflow documented |
| Edit-Draft-Publish pattern | product/x-cutting/edit-draft-publish.md | State machine preserved |
| Persona specifications | product/personas/ (6 personas) | Detailed profiles |
| Purchase order lifecycle | current-system/functional/procurement/order-lifecycle.md | 10-state machine documented |
| Multi-repo development | process/craft/implementation/multi-repo-development.md | Full guide |
| API testing with Bruno | process/craft/verification-and-validation/api-testing-bruno.md | Complete |
| PlantUML guide | about/authoring/plantuml-guide.md | Expanded from original |
| AWS account creation | process/craft/deployment-and-release/aws-account-creation.md | Procedure preserved |
| Postgres bastion access | process/craft/operations-and-monitoring/postgres-bastion.md | Procedure preserved |
| All domain information model entities | domain/information-model/ (27 files) | Expanded from original |
| All runtime/infrastructure docs | current-system/runtime/ (13 files) | Full coverage |
Product Areas Overview (M-1) — RESOLVED. Created product/index.md and vision/functional/index.md.Data Authority Implementation Guide (M-4) — RESOLVED. Created process/craft/implementation/data-authority-endpoint-guide.md.Data Authority Limitations (M-5) — RESOLVED. Created current-system/architecture/data-authority-limitations.md, verified against current implementation.
Bulk Operations Specification (P-3) — RESOLVED. Created product/features/general-behaviors/bulk-operations.md.DrawIO Architecture Diagrams (P-6) — RESOLVED. Migrated 6 SVGs to _assets/ directories with links.OAuth2 Design Rationale (P-1) — RESOLVED. Expanded oauth2-drafts.md with sign-up flow, token augmentation, separate claims server, and decision summary.Data Authority Consumer Guide (P-12) — RESOLVED. Created process/craft/implementation/data-authority-api-guide.md.
Viewpoint Mapping (P-2) — RESOLVED. Created current-system/architecture/viewpoint-mapping.md.Gradle Workflow Diagrams (P-7) — RESOLVED. Migrated 4 PNGs to _assets/ with links in gradle-project-setup.md.Kanban QR Technical Spec (P-4) — RESOLVED. Expanded kanban-cards-module.md with physical QR specification.Kanban Notes Feature (P-5) — RESOLVED. Created product/features/resources/kanban-notes.md and cross-linked from kanban-cards-module.md.PO UI Requirements (P-9) — RESOLVED. Added UI Structure section to purchase-order-feature.md.
PO Implementation Notes (P-10) — RESOLVED. Target exceeds source in depth (332 lines vs 42 lines).Development Pipelines rationale (P-11) — RESOLVED. Added Architectural Context section to build-and-deployment.md.Demo layout assets (P-8) — RESOLVED. Migrated 3 PNGs to demo-specifics/_assets/ with links in pdf-printing.md.
UX Capture/Scanning patterns (former M-2) — Source files were stubs; GEN domain already provides comprehensive coverage.UX Workflow Element patterns (former M-3) — Source file was a stub; no content to migrate.