finos / finos/architecture-as-code
Support Sub-site with docify when detailed-architecture is used.
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 38
Description
## Summary
When a CALM architecture contains nodes with `detailed-architecture` references, docify should create a subsite (nested Docusaurus pages) for the referenced architecture's nodes. Currently, only the top-level nodes are documented.
## Problem Statement
Given this architecture structure in `sample-architecture/`:
`system.json` (root architecture)
```json
{
"nodes": [
{ "unique-id": "ecommerce-system", "name": "E-Commerce System", "node-type": "system" },
{
"unique-id": "payment-service",
"name": "Payment Service",
"node-type": "container",
"details": {
"detailed-architecture": "https://specs.internal/payment-service"
}
},
{ "unique-id": "inventory-service", "name": "Inventory Service", "node-type": "container" }
]
}
```
`payment-service.json` (nested architecture, mapped via `calm-mapping.json`)
```json
{
"nodes": [
{ "unique-id": "api-gateway", "name": "API Gateway", "node-type": "component" },
{ "unique-id": "payment-processor", "name": "Payment Processor", "node-type": "component" },
{ "unique-id": "payment-db", "name": "Payment DB", "node-type": "database" }
]
}
```
### Current Behavior
Running `calm docify` on `system.json` generates:
```
website/docs/
├── index.md
├── nodes/
│ ├── ecommerce-system.md (generated)
│ ├── inventory-service.md (generated)
│ └── payment-service.md (generated, but no link to nested nodes)
└── relationships/
└── sys-composition.md
```
The nested nodes (`api-gateway`, `payment-processor`, `payment-db`) from `payment-service.json` are not documented.
### Expected Behavior
```
website/docs/
├── index.md
├── nodes/
│ ├── ecommerce-system.md
│ ├── inventory-service.md
│ ├── payment-service.md (links to subsite)
│ └── payment-service/ (subsite for nested architecture)
│ ├── index.md (overview of Payment Service internals)
│ ├── api-gateway.md
│ ├── payment-processor.md
│ └── payment-db.md
└── relationships/
└── ...
```
## User Impact
- Incomplete documentation: Users documenting modular architectures lose visibility into component internals
- Manual workarounds: Teams must run docify multiple times and manually link the outputs
- Broken navigation: No way to drill down from a service to its internal components
## Proposed Solution
1. Detect `detailed-architecture` references during docify processing
2. Resolve references using the existing `calm-mapping.json` URL-to-local mappings
3. Recursively generate subsites for each nested architecture
4. Update parent node pages to include navigation links to the subsite
5. Update Docusaurus sidebar to reflect the hierarchical structure
## Acceptance Criteria
- [ ] Nodes with `detailed-architecture` trigger subsite generation
- [ ] Subsites are created under `docs/nodes/{parent-node-id}/`
- [ ] Parent node page includes a link/section pointing to the subsite
- [ ] Sidebar navigation reflects the hierarchy
- [ ] Works with VSCode extension's "Create Website" command
- [ ] Circular references are detected and handled gracefully
## Related Files
- `shared/src/docify/docifier.ts` - Main docify entry point
- `shared/src/template/template-processor.ts` - Template processing logic
- `shared/src/template/template-bundles/docusaurus/` - Docusaurus templates
- `calm-plugins/sample-architecture/` - Test case with nested architecture
Contributor guide
Assessment
This issue has not been assessed yet.