finos / finos/architecture-as-code

Version-agnostic `detailed-architecture` resolution (latest alias)

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.