Architecture Overview
This section contains C4 model diagrams and supplementary architecture documentation for Invowk. These diagrams help developers understand the system structure, execution flows, and design decisions.
Diagram Overview
| Diagram | Type | Purpose |
|---|---|---|
| C4 Context (C1) | C4 Model | System boundaries, users, external systems |
| C4 Container (C2) | C4 Model | Internal components and data stores |
| C4 Component: Runtime (C3) | C4 Model | Internal structure of the runtime package |
| C4 Component: Container (C3) | C4 Model | Internal structure of the container package |
| Command Execution | Sequence | Temporal flow from CLI to execution |
| Runtime Selection | Flowchart | Decision tree for choosing runtime |
| Discovery Precedence | Flowchart | How commands are found and conflicts resolved |
Reading Order
For newcomers to the codebase:
- Start with C4 Context - Understand what Invowk is and what it interacts with
- Then C4 Container - See the major internal components
- Optionally explore Runtime Components or Container Components - Deep-dive into packages with non-trivial internal structure
- Read Command Execution - Follow the main user journey
- Reference others as needed - Runtime selection and discovery when debugging or extending
Diagram Technology
All diagrams use Mermaid syntax. Mermaid is a JavaScript-based diagramming tool that renders diagrams from text definitions, making them easy to version control and maintain.
Editing Diagrams
The Mermaid Live Editor is useful for testing changes before committing.
C4 Model Background
The C4 model provides a hierarchical way to describe software architecture:
| Level | Name | Description |
|---|---|---|
| C1 | Context | System as black box with external actors |
| C2 | Container | Major deployable/runnable units |
| C3 | Component | Internal modules within containers |
| C4 | Code | Class/code-level details |
For Invowk (a single CLI binary), C1 and C2 are most valuable. C3 (Component) diagrams are provided selectively for packages whose internal structure is genuinely complex — specifically internal/runtime/ (interface segregation, registry pattern, 3 implementations) and internal/container/ (composition via embedding, decorator pattern, functional options). Other packages have flat enough structure that code documentation suffices.
Keeping Diagrams Updated
When making significant architectural changes:
- Check if diagrams need updates - New components, changed relationships, removed features
- Update the relevant diagram(s) - Keep changes focused
- Verify rendering - Test in Mermaid Live Editor or the website preview
- Update tables and text - Diagrams alone may not capture all context