finos / finos/architecture-as-code
Proposal to add architecture query language to interact with the architecture model
- 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
Assessment
This issue has not been assessed yet.