From 5b89c370d5974f057306a52089f14c337565fd1d Mon Sep 17 00:00:00 2001 From: Doan Luu Duc Tai Date: Sat, 31 Oct 2026 17:54:29 -0500 Subject: docs: shorten guides and map repository files --- docs/MAP.txt | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 docs/MAP.txt (limited to 'docs/MAP.txt') diff --git a/docs/MAP.txt b/docs/MAP.txt new file mode 100644 index 0000000..6f5e13d --- /dev/null +++ b/docs/MAP.txt @@ -0,0 +1,175 @@ +Copyright (C) 2026 Doan Luu Duc Tai + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as +published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +along with this program. If not, see . + +FILE MAP + + Public tree: every tracked file, including this map. + Static inventory; update when public paths change. Root: stack/. + Private/generated trees below list roles only; contents stay unlisted. + +stack/ Personal service source, build recipes and recovery tooling. +|-- .cargo/ Cargo command aliases. +| `-- config.toml Cargo stack alias. +|-- crates/ Workspace application/configuration crates. +| |-- chat-crypto/ Fixed-suite Rust and browser cryptography. +| | |-- browser/ Browser crypto types and WASI adapter. +| | | |-- protocol.d.ts Shared typed API, crypto, worker, WASI message contracts. +| | | `-- wasi.ts Browser WASI host: memory, I/O, entropy, command execution. +| | |-- src/ Rust crypto library and executable. +| | | |-- application.rs Protected identities, authentication proofs, message encryption/decryption. +| | | |-- lib.rs Public crypto API and fixed-suite compatibility round trip. +| | | `-- main.rs Native/WASI executable: request input and crypto result output. +| | |-- tests/ Real-browser crypto compatibility tests. +| | | `-- browser.ts Real-browser crypto probe, entropy-failure and network-isolation checks. +| | |-- Cargo.toml Crypto library/probe targets, fixed backend features, dependencies. +| | `-- README.txt Crypto suite, native/WASI build, compatibility checks. +| |-- chat-server/ Private-chat backend and browser client. +| | |-- src/ Rust HTTP server and maintenance entry. +| | | |-- app/ Server argument, HTTP, service and storage modules. +| | | | |-- cli.rs Server flags, listener defaults, maintenance argument conflicts. +| | | | |-- http.rs HTTP routes, packaged assets, response security headers. +| | | | |-- maintenance.rs Server file lock, owner fingerprint, destructive owner reset. +| | | | |-- service.rs Authentication challenges/sessions, authorization, chat operations. +| | | | `-- store.rs SQLite owner metadata, conversations, ciphertext history persistence. +| | | |-- app.rs Server initialization, origin/listener checks, command dispatch. +| | | `-- main.rs Chat server executable entry point. +| | |-- tests/ Chat browser integration and loading-state tests. +| | | |-- browser.ts Chat browser flows, owner/visitor access, packaged backup/restore. +| | | `-- progress.ts Crypto-download progress, unknown length, failure and LibreJS checks. +| | |-- web/ Chat markup, styling and TypeScript client. +| | | |-- app.ts Chat browser UI, credentials, API calls, encrypted conversations. +| | | |-- index.html Chat page markup and public-origin template. +| | | |-- javascript.html Browser JavaScript license/source listing. +| | | |-- style.css Chat page layout, controls, status and conversation styling. +| | | `-- worker.ts One-operation crypto worker; returns result/error, then closes. +| | |-- Cargo.toml Chat HTTP server dependencies and workspace lint inheritance. +| | `-- README.txt Server purpose, local startup, browser-test entry. +| |-- config/ Shared environment/configuration crate. +| | |-- src/ Validated configuration and public-rendering implementation. +| | | `-- lib.rs Root .env parsing/validation, defaults, public-only template values. +| | |-- Cargo.toml Shared configuration crate dependencies and lint inheritance. +| | `-- README.txt Configuration crate responsibilities and public rendering boundary. +| `-- README.txt Workspace crate roles and shared policy. +|-- docs/ Plaintext setup, policy, security and recovery guides. +| |-- CHAT-APPLICATION.txt Chat setup, protected files, user flows, recovery, security limits. +| |-- CHAT-OPENSSL-MIGRATION.txt OpenSSL crypto migration evidence, dependencies, reviewed exceptions. +| |-- CHAT-PRODUCTION.txt Chat release packaging, HTTPS activation, owner setup, production recovery. +| |-- CONFIGURATION.txt Supported root settings, validation, public/private state boundaries. +| |-- LINTING.txt Strict Rust/browser checks, generated-code limits, justified exceptions. +| |-- MAP.txt This public-file tree and private/runtime directory roles. +| |-- OPERATIONS.txt Stack development, encrypted backup/restore, host setup, deployment. +| |-- POLICY.txt License/header, source-comment, configuration, strictness and portability rules. +| `-- TYPESCRIPT.txt Typed browser/worker/test builds, ESLint policy, compiler/test commands. +|-- infra/ Service definitions, host integration and build recipes. +| |-- chat/ Native/WASI/TypeScript/source build scripts. +| | |-- build-browser.sh Link Rust/OpenSSL browser crypto command into WASI WebAssembly. +| | |-- build-native.sh Build static musl management/server commands and native crypto probe. +| | |-- build-openssl-wasi.sh Fetch verified SDK/OpenSSL sources; build browser crypto library. +| | |-- build-source.sh Archive corresponding source, vendored Rust crates and OpenSSL source. +| | |-- build-typescript.sh Install locked dev dependencies; run typed checks and emit browser JS. +| | `-- openssl-wasi.conf OpenSSL build target settings for WASI. +| |-- containers/ Container build contexts. +| | |-- cgit/ cgit image and its nginx/FastCGI process configuration. +| | | |-- .containerignore Restrict cgit build context to required container files. +| | | |-- Containerfile Build pinned Debian cgit/nginx/FastCGI/supervisor image. +| | | |-- cgitrc cgit repository listing, paths and presentation template. +| | | |-- entrypoint.sh Prepare cgit container runtime and start its supervisor. +| | | |-- nginx.conf Serve cgit HTTP/static assets; route CGI through fcgiwrap. +| | | `-- supervisord.conf Run nginx and fcgiwrap inside the cgit container. +| | `-- chat/ Prebuilt chat image recipe. +| | `-- Containerfile Package prebuilt static chat server and web/crypto assets. +| |-- searxng/ Search service configuration. +| | `-- settings.yml SearXNG defaults: private instance, rate limiting, HTML search. +| |-- Caddyfile Production domain routing, HTTPS, WKD and service reverse proxies. +| |-- Caddyfile.local Loopback development routing without public certificate requests. +| |-- host-setup.sh Debian ops-user Podman packages, UID/GID checks, low ports and linger. +| |-- podman.conf Legacy Podman override selecting slirp4netns rootless networking. +| |-- services.toml Service images, mounts, environment allowlists, security and health probes. +| `-- stack.service Systemd user boot unit for ~/stack start/stop. +|-- src/ Management executable source. +| |-- app/ Management command implementation modules. +| | |-- archive.rs Consistent snapshots, encrypted exports and validated directory restores. +| | |-- chat.rs Chat build/package artifacts, container settings and owner administration. +| | |-- cli.rs Management subcommands, flags and argument validation. +| | |-- files.rs Safe filesystem/archive operations, manifests and hashes. +| | |-- images.rs Export/import exact container images; enforce platform and content locks. +| | |-- process.rs Run child processes; capture output and report failures/status. +| | |-- project.rs Discover/lock project; settings, Podman commands, service lifecycle. +| | |-- release.rs Build checked release archives; validate/install production artifacts. +| | `-- render.rs Render per-mode Caddy, website and cgit configuration. +| |-- app.rs Management command dispatch, check pipeline and license generation. +| `-- main.rs Management executable entry point. +|-- tests/ Shared first-party browser-test helpers. +| `-- browser-support.ts Shared browser-test response validators, server and browser cleanup helpers. +|-- web/ Main-site template, styles, licenses and public key discovery. +| |-- .well-known/ Standard public discovery endpoints. +| | `-- openpgpkey/ WKD public-key discovery tree. +| | |-- hu/ Direct WKD hashed-user key files. +| | | `-- t76q8xqkeassgy1kr38re1ppj6cpc1dp Owner public key for direct WKD lookup. +| | |-- luuduct.ai/ Advanced WKD namespace for luuduct.ai. +| | | |-- hu/ Advanced WKD hashed-user key files. +| | | | `-- t76q8xqkeassgy1kr38re1ppj6cpc1dp Same owner public key for advanced luuduct.ai WKD lookup. +| | | `-- policy Advanced WKD policy marker for luuduct.ai. +| | `-- policy Direct WKD policy marker. +| |-- THIRD-PARTY-LICENSES.html Generated Rust dependency attribution and full license texts. +| |-- index.html Main-site public links, identity and service-origin template. +| `-- styles.css Main-site visual layout, links and tooltips. +|-- .env.example Public settings template; private-value placeholders. +|-- .gitattributes Whitespace handling for generated third-party license HTML. +|-- .gitignore Exclude secrets, runtime state, dependencies, build output. +|-- Cargo.lock Exact Rust dependency versions and source checksums. +|-- Cargo.toml Management binary, workspace members, dependencies, strict lints. +|-- LICENSE Unmodified GNU AGPLv3 license text; sources allow later versions. +|-- README.txt Project entry: setup, commands, checks, documentation links. +|-- about.hbs HTML template for generated Rust dependency licenses. +|-- about.toml License-page acceptance list and private-package handling. +|-- clippy.toml Reviewed duplicate-crate exceptions for Clippy. +|-- deny.toml Dependency advisory, license, source and duplicate-version policy. +|-- eslint.config.ts Typed ESLint rules and per-environment file scopes. +|-- package-lock.json Exact npm dev dependency versions, integrity and dependency graph. +|-- package.json Browser tooling dependencies and npm check/build/test commands. +|-- rust-toolchain.toml Pinned Rust version, formatting/lint components and target triples. +|-- tsconfig.browser.json Browser main-thread and WASI-host compiler scope. +|-- tsconfig.json Shared strict TypeScript compiler options. +|-- tsconfig.tests.json Node browser-automation compiler scope. +|-- tsconfig.tools.json Node ESLint configuration compiler scope. +`-- tsconfig.worker.json Web-worker compiler scope, separate from DOM globals. + +PRIVATE AND GENERATED PATHS — NOT PUBLIC SOURCE + + .env Sole private root configuration; never commit. + .git/ Local Git objects, refs, hooks and repository settings. + .tools/ Downloaded toolchains, build tools, sources and caches. + bin/ Prebuilt management/chat commands and packaged chat assets. + dist/ Locally built release tarballs and checksum files. + node_modules/ Locked npm development dependencies; recreated by npm ci. + target/ Cargo build output, WASM targets and generated rustdoc. + var/ Private/generated project state; excluded from Git. + backups/ Imported backup archives and recovery test destinations. + build/ Generated TypeScript, source/vendor bundles and build work. + data/ Persistent application databases, TLS keys and Git repos. + caddy/ ACME account/certificate keys, Caddy data/configuration. + chat/ Production chat database: owner identity and ciphertext. + chat-local/ Isolated local chat database and server state. + repos/ Served bare Git repositories; separate from root .git/. + searxng/ Runtime search configuration and persistent service files. + exports/ Encrypted application backups and checksum files. + incoming/ Copied release archives and temporary deployment bootstrap. + podman/ Recreated container storage/run state; never transfer as backup. + graphify/ Public-source graph index, visual map and extraction artifacts. + + Other var/ paths may hold generated fixtures or temporary work. This map does + not enumerate private files. Backups must keep .env and var/data; public Git + alone cannot recover services. See OPERATIONS.txt. -- cgit v1.2.3