C4 System Context Diagram (C1)
This diagram shows Invowk from the highest level - the system boundaries, users, and external systems it interacts with.
Diagram
Key Actors
| Actor | Description |
|---|---|
| Developer | Primary user who creates invowkfile.cue files and runs commands. Defines command implementations across different runtimes. |
| Team Member | Consumes shared modules (.invowkmod directories) and runs commands defined by others. Benefits from portable, reproducible commands. |
External Systems
| System | Purpose | Protocol |
|---|---|---|
| Docker Engine | Container runtime for isolated command execution. Provides reproducible environments. | Docker CLI/API |
| Podman Engine | Alternative rootless container runtime. Preferred for security-conscious environments. | Podman CLI |
| Git Repositories | Source for remote module dependencies. Enables sharing and versioning of command modules. | Git protocol (HTTPS/SSH) |
| Host Shell | Native command execution. Uses bash/sh on Unix, PowerShell on Windows. | Process exec/spawn |
| Filesystem | Storage for configuration, invowkfiles, modules, and scripts. | File I/O |
Key Boundaries
What Invowk Owns
- Command discovery and resolution
- Runtime selection and execution
- Module dependency management
- Configuration parsing and validation
What Invowk Delegates
- Actual command execution (to shells or containers)
- Container image management (to Docker/Podman)
- Version control operations (to Git)
- Filesystem operations (to OS)
Design Decisions Visible at This Level
-
Multi-Runtime Support: Invowk doesn't mandate a single execution environment. Users choose native shell for speed, virtual shell for portability, or containers for isolation.
-
Container Engine Abstraction: Both Docker and Podman are supported with automatic fallback, reducing vendor lock-in.
-
Git-Based Module Distribution: Remote modules use Git for versioning and distribution, leveraging existing infrastructure rather than creating a custom registry.
-
Filesystem-Centric Configuration: All configuration uses local files (CUE format), enabling version control and team sharing.
Related Diagrams
- C4 Container Diagram (C2) - Zoom into Invowk's internal structure
- Command Execution Sequence - Temporal flow of command execution
- Runtime Selection Flowchart - How runtimes are chosen