finos / finos/architecture-as-code

Support Sub-site with docify when detailed-architecture is used.

Open
#2,068 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.