finos / finos/architecture-as-code
Version-agnostic `detailed-architecture` resolution (latest alias)
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 38
Description
## Feature Proposal
### Target Project:
calm-hub, calm-hub-ui
### Description of Feature:
Support a `latest` version alias for architecture, pattern, and standard URLs so that `details.detailed-architecture` cross-references don't break on every version bump.
### User Stories:
As an architecture maintainer, I want to reference another architecture without pinning a specific version so that my cross-document links survive re-imports without manual updates.
### Current Limitations:
`detailed-architecture` requires a full versioned URL:
/calm/namespaces/{ns}/architectures/{slug}/versions/1.0.3
Every `calm hub push` increments the version, breaking all references from other documents. In a model with 100+ components and cross-namespace landscapes, keeping these URLs in sync is unsustainable.
### Proposed Implementation:
- **API**: `GET /calm/namespaces/{ns}/architectures/{slug}/versions/latest` resolves to the most recent version (by semver or insertion order). Same for patterns and standards.
- **UI**: When navigating a `detailed-architecture` URL containing `/versions/latest` (or without a `/versions/` segment at all), resolve to the latest version before rendering.
- **`$id`**: Documents keep their concrete version in `$id` for immutability. Only the *reference* in `detailed-architecture` uses `latest`.
Alternatively, support a versionless URL that defaults to latest:
/calm/namespaces/{ns}/architectures/{slug}
### Alternatives Considered:
- **Always reset Hub and re-import at 1.0.0** — works for local dev but prevents incremental updates and version history.
- **Post-import script to patch all referencing files** — fragile, adds complexity to every import pipeline.
### Testing Strategy:
- Unit: resolver returns latest version when `latest` or no version is specified.
- Integration: `detailed-architecture` navigation in the UI with `latest` alias, versionless URL, and explicit version all resolve correctly.
### Documentation Requirements:
- API reference: document the `latest` alias on version endpoints.
- User guide: recommend `latest` for `detailed-architecture` cross-references.
### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed
### Additional Context:
Related to the versioned drill-down navigation in CALM Hub. The `details.detailed-architecture` field is a plain string (`core.json#/defs/node`), so no schema change is needed — only the Hub API and UI need to handle `latest` resolution.
Contributor guide
Research direction
Start by locating the API version endpoints and the UI navigation for detailed-architecture URLs in calm-hub and calm-hub-ui. Add or run resolver tests for latest, versionless, and explicit versions, then verify integration navigation and update the API reference and user guide. Done means all three URL forms resolve correctly while document $id values remain concrete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, documentation, frontend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100