finos / finos/architecture-as-code

Proposal to add architecture query language to interact with the architecture model

Open
#2,389 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

## Feature Proposal
This proposal introduces Architecture Query Language (AQL), a declarative, domain-specific query language designed to enable efficient, expressive interactions with CALM architecture data. AQL will provide architects, developers, and tools with a standardized way to query, filter, aggregate, and transform architecture model data without requiring custom code or deep JSON navigation.

### Target Project:
calm-hub, calm-cli, calm-server
Probably will touch all repos

### Description of Feature:
Currently, users interacting with CALM architecture models face several challenges:

1. **No Standard Query Syntax**: There is no consistent, standardized way to query CALM model data. Users must either:
- Write custom code to parse and filter JSON structures
- Use generic JSON query tools that lack architecture-domain understanding
- Manually navigate deeply nested JSON structures

2. **Limited Composability**: Complex architectural queries (e.g., "find all systems that communicate with Finance services and have unmet security controls") require extensive custom logic
3. **Tool Integration Friction**: Tools, UIs, and analytical platforms that consume CALM data lack a unified interface, making integration costly and error-prone
4. **Knowledge Barrier**: Users without strong programming backgrounds cannot easily explore and analyze architecture models
5. **No Architecture Semantics**: Generic query languages do not understand CALM concepts like "systems," "nodes," "interactions," "controls," "data flows," etc.

**Solution**: Architecture Query Language (AQL)
AQL is a lightweight, SQL-like query language purpose-built for CALM architectures, enabling:

- **Familiar Syntax**: SQL-inspired syntax that architects and developers already understand
- **Architecture Semantics**: First-class support for CALM concepts (systems, nodes, interactions, controls, data flows)
- **Composition**: Support for filtering, aggregation, joins, and transformations
- **Multiple Frontends**: Query as a CLI tool, REST API, or embedded library
- **Multiple Backends**: Execute against CALM JSON files, CALM Hub, or in-memory models
#### Example Queries

> -- Find all systems in the Finance domain
`SELECT * FROM systems WHERE domain = 'Finance'`

> -- Find all synchronous communication patterns
`SELECT source.id, target.id, interaction_type
FROM interactions
WHERE interaction_type = 'synchronous'`

> -- Aggregate: Count systems by deployment environment
`SELECT deployment_environment, COUNT(*) as system_count
FROM systems
GROUP BY deployment_environment`

> -- Complex query: Identify high-risk architectures
`SELECT s.id, s.name, COUNT(c.id) as unmet_controls
FROM systems s
LEFT JOIN controls c ON s.id = c.system_id
WHERE c.status = 'unmet' OR c.priority = 'critical'
GROUP BY s.id, s.name
HAVING COUNT(c.id) > 2
ORDER BY unmet_controls DESC`

### User Stories:
As a CTO, I want a mechanism to query the architecture of my application to find any open compliance failures without having to interact with API or JSON data

### Current Limitations:
...describe why this functionality isn't possible with the current implementation...

### Proposed Implementation:
...provide details of the intended implementation approach, including:
- Technical design considerations
- API changes (if applicable)
- Data model changes (if applicable)
- Dependencies on other components

### Alternatives Considered:
...what other approaches were considered and why were they rejected?

### Testing Strategy:
...how will this feature be tested? Include unit, integration, and any other testing considerations...

### Documentation Requirements:
...what documentation will need to be created or updated?

### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed

### Additional Context:
...add any other context, diagrams, mockups, or screenshots about the feature request here...

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.