From ed0458633b73a6cbdfd466c42528bcbd0dd738a9 Mon Sep 17 00:00:00 2001
From: Sunil Thakares <sunil@thakares.com>
Date: Wed, 13 May 2026 16:17:17 +0530
Subject: [PATCH] Refine architecture and design philosophy documentation

---
 docs/ARCHITECTURE.md      | 26 ++++++++++++++++++++++++++
 docs/DESIGN-PHILOSOPHY.md | 24 ++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 docs/DESIGN-PHILOSOPHY.md

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index d4e3a90..9c906ff 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -39,6 +39,32 @@ activity, correct WASM execution, chain state synchronisation, and a valid
 Ed25519 signature over a time-windowed payload. For an automated client, the
 synchronisation burden alone makes scaled operation expensive.
 
+### High-Level Design
+
+- **Core**: Rust + Axum (async web framework)
+- **Storage**: In-memory SQLite (fast, ephemeral per process — restarts are clean)
+- **Client**: WASM + Rust (runs in browser for proof generation)
+- **Security Model**: Behavioral analysis + hash chaining + entropy scoring
+- **Deployment**: Static musl binary, systemd service, optional Docker
+
+### Key Components
+
+- `shared/` — Types, constants, crypto primitives used by server and WASM
+- `server/` — Axum routes, session management, trust engine, rate limiting, cleanup tasks
+- `wasm/` — Client-side proof generation
+- `frontend/` — Static assets served by the application
+
+### Unix-Native Design Decisions
+
+- Runs as a proper systemd service with strict sandboxing
+- All state is either in-memory or in standard locations (`/run/`, `/var/log/`, `/etc/`)
+- Graceful shutdown and reload support via signals
+- Logging designed for `journalctl` and structured parsing
+- Configuration will be fully runtime (no recompile needed)
+
+### Design Goal
+
+ChronoSeal should feel as natural to use as `nginx` or `redis-server` on a Linux system.
 ---
 
 ## Component Map
diff --git a/docs/DESIGN-PHILOSOPHY.md b/docs/DESIGN-PHILOSOPHY.md
new file mode 100644
index 0000000..732af36
--- /dev/null
+++ b/docs/DESIGN-PHILOSOPHY.md
@@ -0,0 +1,24 @@
+# ChronoSeal Design Philosophy
+
+**"Files as a Software" (FaaS) — Everything is a file.**
+
+ChronoSeal is intentionally designed as a **first-class citizen of Linux**. The entire application behaves as if it is a well-designed native file in the Unix filesystem.
+
+### Core Beliefs
+
+- The CLI is the single source of truth.
+- The application must be controllable, inspectable, configurable, and composable using standard Unix tools.
+- Any GUI, TUI, or web interface is only a thin wrapper.
+- Production robustness and decades-long maintainability take precedence over rapid development.
+
+### Key Principles Applied
+
+- **Behave like a file**: Clear interface, predictable behavior, proper lifecycle (open/read/write/close semantics via signals and commands).
+- **Composability**: Works naturally with pipes, redirection, systemd, scripts, and orchestration tools.
+- **Observability**: Everything important is exposed as text or structured data.
+- **Minimal Friction**: One-line installer, excellent `--help`, proper man pages.
+- **Respect for the OS**: Follows FHS, XDG, systemd best practices, and hardened security model.
+
+This philosophy guided the complete refactoring of ChronoSeal.
+
+**Status**: Core architecture and systemd integration completed. Rich CLI, configuration system, and installer are in progress.
\ No newline at end of file