Home

Top Level System

A universal modular C microkernel that connects hot-loadable modules through path-based message routing. Everything is a path. Every interaction is a message.

The main program is named portal because it is the entry point — the door through which you access this universe. You don't interact with modules directly, you don't call languages directly, you don't touch devices directly. You go through the portal, and the portal routes you to wherever you need to be.

At a Glance

Metric	Value
Lines of C	~28,000
Modules	50 hot-loadable .so
Scripting Languages	4 (Lua, Python, C, Pascal)
Interfaces	6 (CLI, HTTP, HTTPS, TCP, UDP, SSH)
Storage Backends	3 (File, SQLite, PostgreSQL)
License	GPL-2.0

Architecture

         Top Level System
    ┌────────────────────────────────────┐
    │   portal (the entry point)         │
    │                                    │
    │   ┌──────────────────────────┐     │
    │   │      Core Engine         │     │
    │   │  ┌────────┐ ┌────────┐  │     │
    │   │  │ Router  │ │  ACL   │  │     │
    │   │  │ (FNV1a) │ │(labels)│  │     │
    │   │  └────────┘ └────────┘  │     │
    │   │  ┌────────┐ ┌────────┐  │     │
    │   │  │Events  │ │Storage │  │     │
    │   │  │Pub/Sub │ │ 3-way  │  │     │
    │   │  └────────┘ └────────┘  │     │
    │   └──────────────────────────┘     │
    │                                    │
    │   ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐       │
    │   │M1│ │M2│ │M3│ │..│ │50│       │
    │   └──┘ └──┘ └──┘ └──┘ └──┘       │
    │   Hot-loadable modules (.so)       │
    └────────────────────────────────────┘

Core Provides

• Path-based routing — O(1) FNV-1a hash table lookup with wildcard fallback
• Universal message system — one portal_msg_t structure for all communication
• Label-based ACL — groups on users, labels on paths, intersection = access
• Hot-loadable modules — load, unload, reload at runtime with reference counting
• Cross-platform event loop — embedded libev (epoll/kqueue/select)
• Module crash isolation — setjmp/longjmp, the core survives module segfaults
• Message tracing — trace_id, timestamp, hop count on every message
• Pub/Sub events — ACL-controlled event subscriptions with pattern matching

Quick Start

./configure
make
./portal -c portal.conf

Connect via CLI:

./portal -r                    # local UNIX socket
ssh admin@localhost -p 2222    # remote SSH
curl http://localhost:8080/api/health  # HTTP API

Wiki Pages

Getting Started

• Philosophy — The 14 Laws of Top Level System
• Architecture — Core engine internals
• Building — Compile and install

Reference

• Modules — All 50 modules overview
• Federation — Multi-instance networking
• Scripting Engines — Lua, Python, C, Pascal
• Core API — Types, methods, status codes

Modules by Category

• Infrastructure: mod_cli, mod_web, mod_node, mod_ssh, mod_config_sqlite, mod_config_psql
• Data & Messaging: mod_cache, mod_kv, mod_shm, mod_queue, mod_websocket, mod_mqtt, mod_email, mod_file
• Logic & Scripting: mod_logic, mod_logic_lua, mod_logic_python, mod_logic_c, mod_logic_pascal
• System & Monitoring: mod_metrics, mod_health, mod_sysinfo, mod_process, mod_log, mod_audit, mod_cron, mod_scheduler, mod_worker, mod_backup
• Network & Integration: mod_proxy, mod_dns, mod_http_client, mod_webhook, mod_api_gateway, mod_tunnel, mod_acme
• Security: mod_firewall, mod_crypto, mod_ldap, mod_validator
• IoT: mod_iot, mod_gpio, mod_serial
• Compression: mod_xz, mod_gzip
• Rendering: mod_template, mod_admin
• Examples: mod_hello, mod_myapp

Developer

• Module Development Guide — Write your own module
• Module Interface — The 4 required exports

Links

• Website: 7ks.ai/tls
• Repository: github.com/garacil/TopLevelSystem