WEBcodeX1 · clauspruefer · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/README.md b/README.md
diff --git a/config/README.md b/config/README.md
@@ -0,0 +1,7 @@
+# 1. Runtime Configuration
+
+This directory contains the JSON configuration used by the server runtime.
+
+## 1.1. Contents
+
+- `config.json`: sample / default server configuration covering base paths, TCP options, runtime user/group, MIME types, CPU binding, and virtual host namespace routing.
diff --git a/image/README.md b/image/README.md
@@ -0,0 +1,8 @@
+# 1. Project Artwork
+
+This directory contains the FalconAS logo assets used by the project documentation.
+
+## 1.1. Contents
+
+- `falconas-logo.png`: rendered logo used by the root `README.md`.
+- `falconas-logo.xcf`: editable GIMP source file for the logo artwork.
diff --git a/image/falconas-logo.png b/image/falconas-logo.png
diff --git a/image/falconas-logo.xcf b/image/falconas-logo.xcf
diff --git a/lib/README.md b/lib/README.md
@@ -1,14 +1,9 @@
-# Internal C++ Libraries
+# 1. Internal C++ Libraries
 
-The following C++ Libraries are used internally by the project.
+This directory contains the reusable libraries that are built before the main `falcon-as` server and linked into tests.
 
-## 1. Event Library
+## 1.1. Subdirectories
 
-The **Event Library** is a tiny library providing a simple callback mechanism.
-
-## 2. HTTP/1.1 Library
-
-The **HTTP/1.1 Library** is used to
-
-- Parse HTTP Requests / Headers
-- Generate HTTP Requests / Headers
+- [`event/`](./event/): small shared callback / event helper library (`libevent2`).
+- [`http/`](./http/): static HTTP parsing and message generation library (`httpparser`).
+- [`xml/`](./xml/): static Xerces-C++ backed XML parsing library (`xmlparser`).
diff --git a/lib/event/README.md b/lib/event/README.md
@@ -0,0 +1,9 @@
+# 1. Event Helper Library
+
+This directory contains the lightweight event / callback helper that is built as the shared library `libevent2`.
+
+## 1.1. Contents
+
+- `Event.hpp`: public interface for registering and dispatching callbacks.
+- `Event.cpp`: implementation of the event helper.
+- `CMakeLists.txt`: builds and installs the shared library.
diff --git a/lib/http/README.md b/lib/http/README.md
@@ -0,0 +1,11 @@
+# 1. HTTP Parser / Generator Library
+
+This directory contains the internal static library `httpparser` that is linked into the server, unit tests, and benchmark targets.
+
+## 1.1. Contents
+
+- `httpparser.cpp` / `httpparser.hpp`: default C++23 parser implementation using `std::string_view`, `std::span`, and heterogeneous lookups.
+- `httpparser-cpp11.cpp` / `httpparser-cpp11.hpp`: legacy parser implementation enabled with `-DUSE_LEGACY_CPP11=ON`.
+- `httpgenerator.cpp` / `httpgenerator.hpp`: HTTP response / message generation helpers.
+- `httpconstants.hpp` and `httpconstants-cpp11.hpp`: parser and generator constants for the corresponding implementation.
+- `CMakeLists.txt`: selects the active parser implementation and builds the static archive.
diff --git a/lib/xml/README.md b/lib/xml/README.md
@@ -0,0 +1,10 @@
+# 1. XML Parser Library
+
+This directory contains the internal static library `xmlparser` used for XML validation and message parsing.
+
+## 1.1. Contents
+
+- `xmlparser.hpp` / `xmlparser.cpp`: parser interface and implementation.
+- `xmlconstants.hpp`: XML-related constants used by the parser.
+- `static-dtd.hpp`: embedded DTD support used by the parser layer.
+- `CMakeLists.txt`: resolves the Xerces-C++ dependency and builds the static archive.
diff --git a/ports/README.md b/ports/README.md
@@ -1,5 +1,7 @@
-# Ported Systems
-This directory contains ports to multiple systems.
+# 1. Ported Systems
 
-## Arduino
-The ./arduino subdir contains ports to arduino based microcontrollers. 
+This directory contains platform-specific ports of reusable FalconAS components.
+
+## 1.1. Subdirectories
+
+- [`arduino/`](./arduino/): microcontroller-focused cross-builds of the HTTP parser library for ESP32 targets.
diff --git a/ports/arduino/README.md b/ports/arduino/README.md
@@ -1,5 +1,10 @@
-# ESP32-C3
-The `./esp32c3` subdir contains the first port to the ESP32-C3 based RISCV32 single core SoC board (ESPRESSIF).
+# 1. Arduino / ESP-IDF Ports
 
-# ESP32-S3
-The `./esp32s3` subdir contains the port to the ESP32-S3 based XTENSA 32-bit dual core SoC board (ESPRESSIF).
+This directory contains cross-build configurations for reusing the internal HTTP parser library on ESP-IDF based ESP32 targets.
+
+## 1.1. Subdirectories
+
+- [`esp32c3/`](./esp32c3/): RISCV32 based ESP32-C3 build configuration.
+- [`esp32s3/`](./esp32s3/): Xtensa based ESP32-S3 build configuration.
+
+Each port builds and installs a target-specific static `httpparser.a` archive together with its public headers.
diff --git a/scripts/README.md b/scripts/README.md
@@ -1,4 +1,14 @@
-# Install Scripts
+# 1. Installation and System Scripts
 
-OS install scripts reside here.
+This directory contains helper scripts used during installation and system preparation.
 
+## 1.1. Contents
+
+- `add_user_group.sh`: creates the runtime user and group expected by the server.
+- `cp_etc.sh`: copies packaged configuration files into their target location.
+- `install_startup_script.cmake`: selects the startup integration matching the detected init system.
+- `mk_www.sh`: prepares the web root used by the example setup.
+- `patch_etc_hosts.sh`: adds local hostname mappings used by the sample namespaces.
+- `set-transparent-hugepages.sh`: applies hugepage related runtime settings.
+- `ulimit.sh`: raises the open-file limit for high-connection workloads.
+- [`startup/`](./startup/): init-system specific service definitions.
diff --git a/scripts/startup/README.md b/scripts/startup/README.md
@@ -1,86 +1,17 @@
-# Startup Scripts
+# 1. Startup Script Variants
 
-This directory contains startup scripts for the Falcon HTTP Application Server.
+This directory contains service definitions for the init systems currently supported by the installer.
 
-## SystemD (Ubuntu, Debian 12+)
+## 1.1. Subdirectories
 
-To install and enable the systemd service:
+- [`systemd/`](./systemd/): service unit for modern Linux distributions.
+- [`openrc/`](./openrc/): OpenRC service wrapper.
+- [`init.d/`](./init.d/): SysVinit compatible startup script.
 
-```bash
-# Copy service file to systemd directory
-sudo cp systemd/falcon-as.service /etc/systemd/system/
+The top-level installer logic in [`../install_startup_script.cmake`](../install_startup_script.cmake) chooses one of these variants during installation.
 
-# Reload systemd configuration
-sudo systemctl daemon-reload
+## 1.2. Manual Installation Quick Reference
 
-# Enable service to start on boot
-sudo systemctl enable falcon-as
-
-# Start the service
-sudo systemctl start falcon-as
-
-# Check service status
-sudo systemctl status falcon-as
-```
-
-## OpenRC (Devuan, Gentoo, Alpine)
-
-To install and enable the OpenRC init script:
-
-```bash
-# Copy init script to init.d directory
-sudo cp openrc/falcon-as /etc/init.d/
-
-# Make it executable (if not already)
-sudo chmod +x /etc/init.d/falcon-as
-
-# Add to default runlevel
-sudo rc-update add falcon-as default
-
-# Start the service
-sudo rc-service falcon-as start
-
-# Check service status
-sudo rc-service falcon-as status
-```
-
-## SysVinit (Debian <= 11, Ubuntu <= 14.04, older systems)
-
-To install and enable the SysVinit init script:
-
-```bash
-# Copy init script to init.d directory
-sudo cp init.d/falcon-as /etc/init.d/
-
-# Make it executable (if not already)
-sudo chmod +x /etc/init.d/falcon-as
-
-# Enable service to start on boot
-sudo update-rc.d falcon-as defaults
-
-# Start the service
-sudo service falcon-as start
-# or
-sudo /etc/init.d/falcon-as start
-
-# Check service status
-sudo service falcon-as status
-# or
-sudo /etc/init.d/falcon-as status
-
-# Stop the service
-sudo service falcon-as stop
-
-# Restart the service
-sudo service falcon-as restart
-```
-
-## Important Notes
-
-All startup scripts include:
-- **ulimit settings**: Sets maximum open files to 1,000,000
-- **Transparent hugepages**: Sets vm.nr_hugepages to 1024
-- **User/Group**: Runs as `falcon-http` user and group
-- **Working directory**: `/var/www`
-
-Make sure the `falcon-http` user and group exist before starting the service (see `/scripts/add_user_group.sh`).
+- **systemd:** copy `systemd/falcon-as.service` to `/etc/systemd/system/`, then run `systemctl daemon-reload` and `systemctl enable --now falcon-as`.
+- **OpenRC:** copy `openrc/falcon-as` to `/etc/init.d/`, make it executable, then run `rc-update add falcon-as default` and `rc-service falcon-as start`.
+- **SysVinit:** copy `init.d/falcon-as` to `/etc/init.d/`, make it executable, then run `update-rc.d falcon-as defaults` and `service falcon-as start`.
diff --git a/scripts/startup/init.d/README.md b/scripts/startup/init.d/README.md
@@ -0,0 +1,7 @@
+# 1. SysVinit Startup Files
+
+This directory contains the classic `/etc/init.d` startup script variant used on SysVinit based systems.
+
+## 1.1. Contents
+
+- `falcon-as`: init script for starting, stopping, and restarting the `falcon-as` service.
diff --git a/scripts/startup/openrc/README.md b/scripts/startup/openrc/README.md
@@ -0,0 +1,7 @@
+# 1. OpenRC Startup Files
+
+This directory contains the OpenRC service wrapper used on systems that manage services with OpenRC.
+
+## 1.1. Contents
+
+- `falcon-as`: OpenRC service script for starting and stopping the `falcon-as` server binary.
diff --git a/scripts/startup/systemd/README.md b/scripts/startup/systemd/README.md
@@ -0,0 +1,7 @@
+# 1. systemd Startup Files
+
+This directory contains the service unit used on systemd-based Linux distributions.
+
+## 1.1. Contents
+
+- `falcon-as.service`: systemd unit file for starting the `falcon-as` server process at boot.
diff --git a/specs/README.md b/specs/README.md
@@ -1,24 +1,9 @@
-# 1. Specifications
-
-Main Specs in [./md/](./md/README.md).
-
-## 1.1. Database
-
-Database Definitions / Performance Test Data [./database/](./database).
-
-## 1.2. Markup
-
-Main Specs / Markup Documents [./md/](./md/README.md).
-
-## 1.3. Portable Document Format
-
-PDF rendered / from Visio [./pdf/](./pdf).
-
-## 1.4. MS Visio
-
-Microsoft Visio Slides [./visio/](./visio).
-
-## 1.5. XML
-
-XML Service Specifications [./xml/](./xml).
-
+# 1. Specifications
+
+This directory groups the protocol and benchmark specification material that accompanies the implementation.
+
+## 1.1. Subdirectories
+
+- [`xml/`](./xml/): XML / DTD protocol definitions and per-subtype specification drafts.
+- [`yang/`](./yang/): YANG representation of the NLAP message model.
+- [`database/`](./database/): database notes for performance-test result storage.
diff --git a/specs/database/README.md b/specs/database/README.md
@@ -0,0 +1,7 @@
+# 1. Database Notes
+
+This directory contains database-oriented notes for storing and analysing performance measurements.
+
+## 1.1. Contents
+
+- `test-performance-db.md`: draft schema and workflow notes for persisting benchmark runs and result metadata.
diff --git a/specs/xml/NLASP-XML-SPECS.md b/specs/xml/NLASP-XML-SPECS.md
diff --git a/specs/xml/README.md b/specs/xml/README.md
@@ -1,15 +1,15 @@
 # 1. XML Service Metadata Specifications
 
-This directory contains XML service metadata specifications for the Next Level Application Protocol (NLAP) sub-protocols.
+This directory contains the XML-oriented protocol material for NLAP.
 
-## 1.1. Table of Contents
+## 1.1. Contents
 
-1. [Next Level Application Metadata Protocol (NLAMP)](./NLAMP-XML-SPECS.md)
-2. [Next Level Application File Protocol (NLAFP)](./NLAFP-XML-SPECS.md)
-3. [Next Level Application Session Protocol (NLASP)](./NLASP-XML-SPECS.md)
-4. [Next Level Application Proxy Protocol (NLAPP)](./NLAPP-XML-SPECS.md)
-5. [Next Level Application Protocol Secure Extension (NLAPS)](./NLAPS-XML-SPECS.md)
+- `nlap.dtd`: shared DTD describing the common NLAP message envelope and elements.
+- `NLAMP-XML-SPECS.md`: metadata protocol draft.
+- `NLAFP-XML-SPECS.md`: file-transfer protocol draft.
+- `NLAPP-XML-SPECS.md`: proxy protocol draft.
+- `NLAPS-XML-SPECS.md`: security extension draft.
 
-## 1.2. Development Status
+## 1.2. Notes
 
-Ongoing RFP / RFC development status: [Exemplary HTTP Processing Protocol Design](https://www.der-it-pruefer.de/network/Exemplary-HTTP-Processing-Protocol-Design)
+The XML parser library and XML parser tests in this repository use these definitions as the current structural reference point.
diff --git a/specs/yang/README.md b/specs/yang/README.md
@@ -0,0 +1,7 @@
+# 1. YANG Specifications
+
+This directory contains the YANG representation of the NLAP message model.
+
+## 1.1. Contents
+
+- `nlap.yang`: YANG 1.1 module derived from `../xml/nlap.dtd`, covering the shared NLAP envelope and the currently modelled sub-protocol fields.
diff --git a/specs/xml/nlap.yang → specs/yang/nlap.yang b/specs/xml/nlap.yang → specs/yang/nlap.yang
diff --git a/src/ASBackend/README.md b/src/ASBackend/README.md
@@ -0,0 +1,8 @@
+# 1. Application Server Backend Headers
+
+This directory contains the backend-specific interface headers used by the application-server process layer.
+
+## 1.1. Contents
+
+- `PythonBackend.hpp`: Python embedding interface used by the default build.
+- `JavaBackend.hpp`: JNI-based backend interface enabled when the project is configured with `-DJAVA_BACKEND=1`.
diff --git a/src/README.md b/src/README.md
@@ -0,0 +1,14 @@
+# 1. FalconAS Server Sources
+
+This directory contains the main application sources that build the `falcon-as` executable.
+
+## 1.1. Main Components
+
+- `main.cpp`: entry point that constructs and starts the server.
+- `Server.*`: socket setup, accept loop, shared-memory setup, and process termination orchestration.
+- `Client*` and `ClientHandler*`: client connection tracking, epoll integration, and request processing.
+- `Configuration*`: JSON configuration loading and namespace / MIME type setup.
+- `Filesystem*`: static file namespace helpers.
+- `ASProcessHandler*`: application-server child process handling for Python or Java backends.
+- `CPU*`, `MemoryManager.hpp`, `SHMVector.hpp`, `Vector.hpp`: low-level runtime helpers.
+- [`ASBackend/`](./ASBackend/): backend-specific interface headers.
diff --git a/test/README.md b/test/README.md
@@ -1,8 +1,10 @@
-# Tests
+# 1. Tests
 
-Tests are devided into the following Sub-Sections.
+This directory contains the CMake-organized test and benchmark tree for FalconAS.
 
-- Evaluation Tests [./eval](./eval)
-- Unit Tests [./unit](./unit)
-- Integration Tests [./integration](./integration)
-- Performace Tests [./performance](./performance)
+## 1.1. Subdirectories
+
+- [`eval/`](./eval/): exploratory and feature-evaluation executables.
+- [`integration/`](./integration/): cross-component tests and end-to-end style checks.
+- [`unit/`](./unit/): focused tests for individual libraries and helpers.
+- [`performance/`](./performance/): benchmark and measurement-oriented executables.
diff --git a/test/eval/JavaJNI/README.md b/test/eval/JavaJNI/README.md
@@ -0,0 +1,10 @@
+# 1. Java JNI Evaluation
+
+This directory contains the optional JNI-based evaluation target for the Java backend path.
+
+## 1.1. Contents
+
+- `test-run-jni.cpp`: Boost.Test executable that exercises the JNI bridge.
+- `WebApp.java` / `WebApp.class`: small Java test application used by the JNI test.
+- `json-java.jar`: bundled JSON dependency required by the Java sample.
+- `CMakeLists.txt`: resolves Java / JNI packages and builds `test-run-jni`.
diff --git a/test/eval/README.md b/test/eval/README.md
@@ -0,0 +1,11 @@
+# 1. Evaluation Tests
+
+This directory contains exploratory targets used to validate implementation ideas or optional runtime integrations.
+
+## 1.1. Contents
+
+- `test-boost-python.cpp`: experiments with the embedded Python integration layer.
+- `test-pointer-ref.cpp`: pointer / reference behavior checks.
+- `test-shmem-vector.cpp`: shared-memory vector experimentation.
+- [`ResultOrder/`](./ResultOrder/): focused result-ordering evaluation target.
+- [`JavaJNI/`](./JavaJNI/): optional JNI evaluation target, built only when `JAVA_BACKEND` is enabled.
diff --git a/test/eval/ResultOrder/README.md b/test/eval/ResultOrder/README.md
@@ -0,0 +1,9 @@
+# 1. Result Order Evaluation
+
+This directory contains an evaluation test for ordering-related behavior.
+
+## 1.1. Contents
+
+- `test-result-order.cpp`: Boost.Test executable built as `test-result-order`.
+- `test-result-order-class.cpp`: helper implementation used by the test executable.
+- `test-result-order.hpp`: declarations shared by the result-order test sources.