# plasticgaming99/vigilante architecture

> Architecture diagram of the GitHub repository plasticgaming99/vigilante, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/plasticgaming99/vigilante
- Repository: https://github.com/plasticgaming99/vigilante

## Overview

1. **What this repo is**
   - `vigilante` is a Linux init system written in V. The main binary is the init daemon itself, intended to run as PID 1 and manage boot targets and services.
   - The architecture is split into the daemon, a small control client (`vigctl`), parsing/configuration, service lifecycle management, and low-level Linux syscall bindings.

2. **Top-level control flow**
   - Startup begins in `main.v`, which likely initializes logging, signal handling, service state, and the event loop.
   - From there, the daemon loads a target/service definition, builds the dependency order, starts required units, and then stays resident to react to process exits, signals, and control requests.

3. **Configuration and unit model**
   - Unit files are TOML-like and define `[info]`, `[service]`, and `[mount]` sections.
   - The service model supports several execution modes: `process`, `fork`, `oneshot`, and `internal`.
   - Units can express ordering and dependency relationships such as `after`, `before`, `depends_on`, `depends_ms`, and `waits_for`, plus mount metadata like target path, filesystem type, options, and read/write requirements.

4. **Parser and unit loading**
   - `parse.v` is the configuration ingestion layer. It turns unit files from `defaulttargets/` and `testfiles/` into internal service/target structures.
   - This is the boundary between declarative boot definitions and the imperative service manager logic.

5. **Service management core**
   - `service_ss.v` appears to contain the service state machine and orchestration logic: starting, tracking, and stopping units, and enforcing dependency/order constraints.
   - This is where target semantics like `default.target`, `multi-user.target`, `networking.target`, `recovery.target`, and shutdown targets are likely composed into a boot graph.

6. **Event-driven runtime**
   - `quickev/` is a lightweight event loop used by the daemon to multiplex process and system events.
   - The `syscall/event_linux.c.v` and related wrappers suggest the event loop is backed by Linux primitives rather than a higher-level runtime, which fits an init system that must remain small and deterministic.

7. **Linux boundary and system integration**
   - `syscall/` contains the low-level Linux interface layer: wrappers for syscalls, sockets, and event handling.
   - This is the repo’s main OS boundary: process creation, waiting, signals, filesystem mounts, and IPC are all mediated here instead of through external libraries.

8. **Signals and process lifecycle**
   - `sighandlers.v` handles process-level signals delivered to init.
   - In an init system, signals are part of the control plane: they typically drive reload, shutdown, poweroff, reboot, or emergency/recovery transitions, and they must integrate with the service state machine.

9. **Boot targets and packaged defaults**
   - `defaulttargets/` contains built-in boot units such as `dbus.service`, `agetty.service`, `dhcpcd.service`, `graphical.target`, `multi-user.target`, `networking.target`, `poweroff.target`, and `reboot.target`.
   - This shows the intended architecture is target-based: the system boots by selecting a target, and targets pull in the services needed for that mode.

10. **Control utility**
   - `vigctl/` is a separate client tool used to interact with the init daemon.
   - The presence of shared structs in `vigctl/lib/struct.v` and socket-related syscall wrappers strongly suggests a local IPC boundary between the CLI and PID 1, likely for service control and status queries.

11. **Logging and observability**
   - `log.v` is the repository’s internal logging layer.
   - For an init system, logging is part of the core control path because early boot failures and service transitions need to be observable even before user space is fully up.

12. **Testing and examples**
   - `testfiles/` provides sample units and targets, while `testprogs/testsvc1sec` provides a small service program used to exercise startup, timing, or dependency behavior.
   - These files are important for understanding the architecture because they reflect the supported unit types, ordering rules, and boot scenarios the daemon is designed to handle.

Main entry points: [`main.v`](https://github.com/plasticgaming99/vigilante/blob/main/main.v) (Init main), [`service_ss.v`](https://github.com/plasticgaming99/vigilante/blob/main/service_ss.v) (Service state), [`defaulttargets/default.target`](https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/default.target) (Default targets), [`parse.v`](https://github.com/plasticgaming99/vigilante/blob/main/parse.v) (Unit parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Init daemon"]
  node_main["Init main<br/>daemon entry<br/>[main.v]"]
  node_service_ss["Service state<br/>orchestration<br/>[service_ss.v]"]
  node_parse["Unit parser<br/>config ingest<br/>[parse.v]"]
  node_sighandlers(("Signal handlers<br/>signal control<br/>[sighandlers.v]"))
  node_log["Logging<br/>observability<br/>[log.v]"]
  node_quickev(("Event loop<br/>runtime loop<br/>[quickev_linux.c.v]"))
end

subgraph group_os["Linux boundary"]
  node_syscall_core["Syscalls<br/>linux api<br/>[syscall.c.v]"]
  node_syscall_linux["Linux syscalls<br/>linux api<br/>[syscall_linux.c.v]"]
  node_event_linux(("Event backend<br/>[event_linux.c.v]"))
  node_socket_linux(("Socket IPC<br/>[socket_linux.c.v]"))
end

subgraph group_client["Control client"]
  node_vigctl_main["vigctl<br/>control cli<br/>[main.v]"]
  node_vigctl_structs["IPC structs<br/>shared schema<br/>[struct.v]"]
end

subgraph group_units["Boot units"]
  node_defaulttargets["Default targets<br/>boot units<br/>[default.target]"]
  node_default_multi["Multi-user<br/>target unit<br/>[multi-user.target]"]
  node_default_graphical["Graphical<br/>target unit<br/>[graphical.target]"]
  node_default_net["Networking<br/>service unit<br/>[networking.target]"]
  node_default_power["Shutdown targets<br/>target unit<br/>[poweroff.target]"]
end

subgraph group_tests["Test assets"]
  node_test_units["Test units<br/>sample units<br/>[default.target]"]
  node_testsvc["Test service<br/>sample service<br/>[testsvc1sec.v]"]
end

node_main -->|"loads units"| node_parse
node_main -->|"drives lifecycle"| node_service_ss
node_main -->|"runs on"| node_quickev
node_main -->|"installs"| node_sighandlers
node_main -->|"logs through"| node_log
node_service_ss -->|"consumes"| node_parse
node_service_ss -->|"reacts to events"| node_quickev
node_service_ss -->|"receives control"| node_sighandlers
node_service_ss -->|"composes"| node_defaulttargets
node_parse -->|"parses"| node_test_units
node_quickev -->|"backs onto"| node_event_linux
node_event_linux -->|"uses"| node_syscall_linux
node_socket_linux -->|"uses"| node_syscall_linux
node_syscall_linux -->|"extends"| node_syscall_core
node_vigctl_main -->|"communicates via"| node_socket_linux
node_vigctl_main -->|"shares schema"| node_vigctl_structs
node_defaulttargets -->|"includes"| node_default_multi
node_defaulttargets -->|"includes"| node_default_graphical
node_defaulttargets -->|"includes"| node_default_net
node_defaulttargets -->|"includes"| node_default_power
node_test_units -->|"exercises"| node_testsvc

click node_main "https://github.com/plasticgaming99/vigilante/blob/main/main.v"
click node_service_ss "https://github.com/plasticgaming99/vigilante/blob/main/service_ss.v"
click node_parse "https://github.com/plasticgaming99/vigilante/blob/main/parse.v"
click node_sighandlers "https://github.com/plasticgaming99/vigilante/blob/main/sighandlers.v"
click node_log "https://github.com/plasticgaming99/vigilante/blob/main/log.v"
click node_quickev "https://github.com/plasticgaming99/vigilante/blob/main/quickev/quickev_linux.c.v"
click node_syscall_core "https://github.com/plasticgaming99/vigilante/blob/main/syscall/syscall.c.v"
click node_syscall_linux "https://github.com/plasticgaming99/vigilante/blob/main/syscall/syscall_linux.c.v"
click node_event_linux "https://github.com/plasticgaming99/vigilante/blob/main/syscall/event_linux.c.v"
click node_socket_linux "https://github.com/plasticgaming99/vigilante/blob/main/syscall/socket_linux.c.v"
click node_vigctl_main "https://github.com/plasticgaming99/vigilante/blob/main/vigctl/main.v"
click node_vigctl_structs "https://github.com/plasticgaming99/vigilante/blob/main/vigctl/lib/struct.v"
click node_defaulttargets "https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/default.target"
click node_default_multi "https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/multi-user.target"
click node_default_graphical "https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/graphical.target"
click node_default_net "https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/networking.target"
click node_default_power "https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/poweroff.target"
click node_test_units "https://github.com/plasticgaming99/vigilante/blob/main/testfiles/default.target"
click node_testsvc "https://github.com/plasticgaming99/vigilante/blob/main/testprogs/testsvc1sec/testsvc1sec.v"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_service_ss,node_parse,node_sighandlers,node_log,node_quickev toneBlue
class node_syscall_core,node_syscall_linux,node_event_linux,node_socket_linux toneAmber
class node_vigctl_main,node_vigctl_structs toneMint
class node_defaulttargets,node_default_multi,node_default_graphical,node_default_net,node_default_power toneRose
class node_test_units,node_testsvc toneIndigo
```

## Components

### Init daemon

PID 1 runtime, orchestration, and boot control.

- [Init main](https://github.com/plasticgaming99/vigilante/blob/main/main.v): daemon entry · Starts the init daemon, wires core runtime pieces, and enters the main loop. · `main.v`
- [Service state](https://github.com/plasticgaming99/vigilante/blob/main/service_ss.v): orchestration · Service and target state machine for starting, stopping, ordering, and dependency handling. · `service_ss.v`
- [Unit parser](https://github.com/plasticgaming99/vigilante/blob/main/parse.v): config ingest · Loads and interprets unit files into internal service and target structures. · `parse.v`
- [Signal handlers](https://github.com/plasticgaming99/vigilante/blob/main/sighandlers.v): signal control · Handles init-level signals that drive shutdown, reload, recovery, and other transitions. · `sighandlers.v`
- [Logging](https://github.com/plasticgaming99/vigilante/blob/main/log.v): observability · Internal logging used across boot, service transitions, and failure reporting. · `log.v`
- [Event loop](https://github.com/plasticgaming99/vigilante/blob/main/quickev/quickev_linux.c.v): runtime loop · Lightweight event dispatcher used to multiplex process and system activity. · `quickev/quickev_linux.c.v`

### Linux boundary

Low-level syscall and event integration.

- [Syscalls](https://github.com/plasticgaming99/vigilante/blob/main/syscall/syscall.c.v): linux api · Core syscall wrappers for process, filesystem, IPC, and other kernel interactions. · `syscall/syscall.c.v`
- [Linux syscalls](https://github.com/plasticgaming99/vigilante/blob/main/syscall/syscall_linux.c.v): linux api · Linux-specific syscall bindings and platform glue. · `syscall/syscall_linux.c.v`
- [Event backend](https://github.com/plasticgaming99/vigilante/blob/main/syscall/event_linux.c.v): event backend · Linux event primitives backing the daemon's event loop. · `syscall/event_linux.c.v`
- [Socket IPC](https://github.com/plasticgaming99/vigilante/blob/main/syscall/socket_linux.c.v): ipc · Socket-related Linux bindings used for daemon and client communication. · `syscall/socket_linux.c.v`

### Control client

User-facing control utility and shared IPC structs.

- [vigctl](https://github.com/plasticgaming99/vigilante/blob/main/vigctl/main.v): control cli · Command-line client for querying and controlling the init daemon. · `vigctl/main.v`
- [IPC structs](https://github.com/plasticgaming99/vigilante/blob/main/vigctl/lib/struct.v): shared schema · Shared data structures used by the client side of daemon communication. · `vigctl/lib/struct.v`

### Boot units

Packaged defaults and sample unit definitions.

- [Default targets](https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/default.target): boot units · Built-in boot targets and services such as default, multi-user, graphical, networking, reboot, and poweroff. · `defaulttargets/default.target`
- [Multi-user](https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/multi-user.target): target unit · Representative target for standard multi-user boot composition. · `defaulttargets/multi-user.target`
- [Graphical](https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/graphical.target): target unit · Representative target for graphical boot composition. · `defaulttargets/graphical.target`
- [Networking](https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/networking.target): service unit · Representative packaged service for bringing up network connectivity. · `defaulttargets/networking.target`
- [Shutdown targets](https://github.com/plasticgaming99/vigilante/blob/main/defaulttargets/poweroff.target): target unit · Representative poweroff and reboot targets for machine transition control. · `defaulttargets/poweroff.target`

### Test assets

Support programs and test unit files.

- [Test units](https://github.com/plasticgaming99/vigilante/blob/main/testfiles/default.target): sample units · Example service, mount, and target files used to exercise parsing and ordering behavior. · `testfiles/default.target`
- [Test service](https://github.com/plasticgaming99/vigilante/blob/main/testprogs/testsvc1sec/testsvc1sec.v): sample service · Small sample service program used to validate service startup and timing behavior. · `testprogs/testsvc1sec/testsvc1sec.v`

## Connections

- Init main → Unit parser: loads units · Startup reads unit definitions and target graphs.
- Init main → Service state: drives lifecycle · Main runtime hands execution to the service state machine.
- Init main → Event loop: runs on · Daemon stays resident in the event loop.
- Init main → Signal handlers: installs · Process-level signals are wired into init control flow.
- Init main → Logging: logs through · Boot and service activity are reported via internal logging.
- Service state → Unit parser: consumes · Service orchestration operates on parsed unit definitions.
- Service state → Event loop: reacts to events · State machine responds to process exits and runtime events.
- Service state → Signal handlers: receives control · Signals trigger shutdown and recovery transitions.
- Service state → Default targets: composes · Built-in targets and services define boot compositions.
- Unit parser → Test units: parses · Sample unit files exercise the configuration boundary.
- Event loop → Event backend: backs onto · Event loop is implemented with Linux event primitives.
- Event backend → Linux syscalls: uses · Event backend depends on Linux-specific syscall bindings.
- Socket IPC → Linux syscalls: uses · Socket IPC is built on Linux syscall wrappers.
- Linux syscalls → Syscalls: extends · Linux-specific layer builds on shared syscall wrappers.
- vigctl → Socket IPC: communicates via · Control client reaches PID 1 over local IPC.
- vigctl → IPC structs: shares schema · Client and daemon exchange common request/response structures.
- Default targets → Multi-user: includes · Representative target unit in the packaged defaults.
- Default targets → Graphical: includes · Representative graphical boot target.
- Default targets → Networking: includes · Representative networking service or target.
- Default targets → Shutdown targets: includes · Representative shutdown and reboot targets.
- Test units → Test service: exercises · Test service binary is used by sample unit definitions.
