Skip to content

Commit 82675b4

Browse files
author
Jonathan D.A. Jewell
committed
Auto-commit: Sync changes [2026-02-21]
1 parent 824aa57 commit 82675b4

5 files changed

Lines changed: 149 additions & 197 deletions

File tree

‎README.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,8 @@ Flatracoon operating system and networking stack.
1212
== License
1313

1414
PMPL-1.0-or-later
15+
16+
17+
== Architecture
18+
19+
See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.

‎TOPOLOGY.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
2+
<!-- TOPOLOGY.md — Project architecture map and completion dashboard -->
3+
<!-- Last updated: 2026-02-19 -->
4+
5+
# flatracoon — Project Topology
6+
7+
## System Architecture
8+
9+
```
10+
┌─────────────────────────────────────────┐
11+
│ APPLICATIONS │
12+
│ (Userspace, Services) │
13+
└───────────────────┬─────────────────────┘
14+
│ System Calls / IPC
15+
▼
16+
┌─────────────────────────────────────────┐
17+
│ OS CORE & NETSTACK │
18+
│ ┌───────────┐ ┌───────────────────┐ │
19+
│ │ OS Kernel │ │ Networking │ │
20+
│ │ (Core) │ │ Stack │ │
21+
│ └─────┬─────┘ └────────┬──────────┘ │
22+
└────────│─────────────────│──────────────┘
23+
│ │
24+
▼ ▼
25+
┌─────────────────────────────────────────┐
26+
│ INTERFACE LAYER │
27+
│ ┌───────────┐ ┌───────────────────┐ │
28+
│ │ Idris2 ABI│ │ Zig FFI │ │
29+
│ │ (Proofs) │ │ (Memory Safety) │ │
30+
│ └─────┬─────┘ └────────┬──────────┘ │
31+
└────────│─────────────────│──────────────┘
32+
│ │
33+
▼ ▼
34+
┌─────────────────────────────────────────┐
35+
│ HARDWARE / HAL │
36+
│ (Bare metal, VirtIO, Drivers) │
37+
└─────────────────────────────────────────┘
38+
39+
┌─────────────────────────────────────────┐
40+
│ REPO INFRASTRUCTURE │
41+
│ Justfile / Mustfile .machine_readable/│
42+
│ ABI-FFI Standards Git Submodules │
43+
└─────────────────────────────────────────┘
44+
```
45+
46+
## Completion Dashboard
47+
48+
```
49+
COMPONENT STATUS NOTES
50+
───────────────────────────────── ────────────────── ─────────────────────────────────
51+
OS CORE (os/)
52+
Kernel Implementation ████░░░░░░ 40% Initial scheduler active
53+
Idris2 ABI (Proofs) ██████████ 100% Type-level layout verified
54+
Zig FFI Bridge ████████░░ 80% Memory safe HAL refining
55+
56+
NETSTACK (netstack/)
57+
Packet Processing ██████░░░░ 60% IPv6-native parsing active
58+
Socket Layer ████░░░░░░ 40% TCP/UDP stubs verified
59+
Hardware Drivers ██░░░░░░░░ 20% VirtIO-net prototyping
60+
61+
REPO INFRASTRUCTURE
62+
Justfile Automation ██████████ 100% Standard build tasks
63+
.machine_readable/ ██████████ 100% STATE.a2ml tracking
64+
Submodule Management ██████████ 100% Component isolation stable
65+
66+
─────────────────────────────────────────────────────────────────────────────
67+
OVERALL: █████░░░░░ ~50% Infrastructure stable, OS maturing
68+
```
69+
70+
## Key Dependencies
71+
72+
```
73+
Idris2 ABI ──────► Zig FFI Bridge ──────► OS Kernel ──────► HAL/Hardware
74+
│ │ │ │
75+
▼ ▼ ▼ ▼
76+
Generated Header ──► Netstack ───────────► Sockets ───────► Applications
77+
```
78+
79+
## Update Protocol
80+
81+
This file is maintained by both humans and AI agents. When updating:
82+
83+
1. **After completing a component**: Change its bar and percentage
84+
2. **After adding a component**: Add a new row in the appropriate section
85+
3. **After architectural changes**: Update the ASCII diagram
86+
4. **Date**: Update the `Last updated` comment at the top of this file
87+
88+
Progress bars use: `█` (filled) and `░` (empty), 10 characters wide.
89+
Percentages: 0%, 10%, 20%, ... 100% (in 10% increments).

‎netstack/orchestrator/lib/flatracoon_orchestrator/application.ex‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,40 @@
11
defmodule FlatracoonOrchestrator.Application do
2-
# See https://hexdocs.pm/elixir/Application.html
3-
# for more information on OTP Applications
4-
@moduledoc false
2+
@moduledoc """
3+
Entry point for the Flatracoon Orchestrator service.
4+
5+
This module defines the primary supervision tree for the orchestration engine,
6+
ensuring that critical services like the Module Registry and Health Monitor
7+
are started and restarted according to the specified strategy.
8+
"""
59

610
use Application
711

812
@impl true
913
def start(_type, _args) do
14+
# SUPERVISION TREE:
15+
# 1. Telemetry: Gathers metrics for the orchestrator.
16+
# 2. DNSCluster: Handles node discovery in a distributed cluster.
17+
# 3. PubSub: Real-time messaging between orchestrator components.
18+
# 4. ModuleRegistry: Authoritative store for FlatRacoon module state (.manifest.ncl).
19+
# 5. HealthMonitor: Periodically checks health_endpoints of deployed modules.
20+
# 6. Endpoint: Starts the Phoenix web server for the dashboard/API.
1021
children = [
1122
FlatracoonOrchestratorWeb.Telemetry,
1223
{DNSCluster, query: Application.get_env(:flatracoon_orchestrator, :dns_cluster_query) || :ignore},
1324
{Phoenix.PubSub, name: FlatracoonOrchestrator.PubSub},
1425
# FlatRacoon orchestrator services
1526
FlatracoonOrchestrator.ModuleRegistry,
1627
FlatracoonOrchestrator.HealthMonitor,
17-
# Start to serve requests, typically the last entry
28+
# Web / API Interface
1829
FlatracoonOrchestratorWeb.Endpoint
1930
]
2031

21-
# See https://hexdocs.pm/elixir/Supervisor.html
22-
# for other strategies and supported options
32+
# STRATEGY: :one_for_one ensures that if a child process crashes,
33+
# only that process is restarted.
2334
opts = [strategy: :one_for_one, name: FlatracoonOrchestrator.Supervisor]
2435
Supervisor.start_link(children, opts)
2536
end
2637

27-
# Tell Phoenix to update the endpoint configuration
28-
# whenever the application is updated.
2938
@impl true
3039
def config_change(changed, _new, removed) do
3140
FlatracoonOrchestratorWeb.Endpoint.config_change(changed, removed)

‎netstack/orchestrator/mix.exs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,17 @@ defmodule FlatracoonOrchestrator.MixProject do
2020
# Type `mix help compile.app` for more information.
2121
def application do
2222
[
23+
# Application Entry Point:
24+
# FlatracoonOrchestrator.Application manages the supervision tree for the orchestration service.
25+
# extra_applications includes runtime_tools for observer/profiling support.
2326
mod: {FlatracoonOrchestrator.Application, []},
2427
extra_applications: [:logger, :runtime_tools]
2528
]
2629
end
2730

2831
def cli do
2932
[
33+
# Default to running tests when executing precommit tasks
3034
preferred_envs: [precommit: :test]
3135
]
3236
end
@@ -40,12 +44,20 @@ defmodule FlatracoonOrchestrator.MixProject do
4044
# Type `mix help deps` for examples and options.
4145
defp deps do
4246
[
47+
# WEB FRAMEWORK:
48+
# Phoenix 1.8+ for the core web/API layer.
4349
{:phoenix, "~> 1.8.3"},
4450
{:phoenix_html, "~> 4.1"},
4551
{:phoenix_live_reload, "~> 1.2", only: :dev},
52+
53+
# UI / REAL-TIME:
54+
# LiveView for real-time orchestration dashboard updates via WebSockets.
4655
{:phoenix_live_view, "~> 1.1.0"},
4756
{:lazy_html, ">= 0.1.0", only: :test},
4857
{:phoenix_live_dashboard, "~> 0.8.3"},
58+
59+
# ASSET PIPELINE:
60+
# esbuild and tailwind for frontend asset compilation.
4961
{:esbuild, "~> 0.10", runtime: Mix.env() == :dev},
5062
{:tailwind, "~> 0.3", runtime: Mix.env() == :dev},
5163
{:heroicons,
@@ -55,8 +67,13 @@ defmodule FlatracoonOrchestrator.MixProject do
5567
app: false,
5668
compile: false,
5769
depth: 1},
70+
71+
# OBSERVABILITY:
72+
# Telemetry for metrics and monitoring integration.
5873
{:telemetry_metrics, "~> 1.0"},
5974
{:telemetry_poller, "~> 1.0"},
75+
76+
# UTILS:
6077
{:gettext, "~> 1.0"},
6178
{:jason, "~> 1.2"},
6279
{:dns_cluster, "~> 0.2.0"},

0 commit comments

Comments
 (0)