Skip to content

Documentation Structure & DRY Rules

This document dictates the architectural boundaries of all .md files in the Silvasonic repository. To prevent documentation drift and maintain the DRY (Don't Repeat Yourself) principle, you MUST adhere to these boundaries.

1. Central Abstractions (Root Level)

  • README.md: Human entry point. Quickstart and "What is this?" Overview.
  • AGENTS.md: AI entry point. Hard constraints, rules, and coding directives.
  • ROADMAP.md: The When. The absolute Source of Truth for milestones, versioning, and feature timing.
  • VISION.md: The Why. The "North Star", architecture ideals, and endgame goals. Does not track release versions.
  • (Note: docs/glossary.md holds the canonical domain language definitions. It lives in docs/ to avoid cluttering the root, but functions as a central abstraction).

2. MkDocs Integration Wrappers

We use MkDocs for our documentation site. Since MkDocs cannot natively render markdown files originating outside the docs/ folder, we use Jinja include wrappers (e.g., `# Silvasonic — Roadmap

Status: v0.8.0 — BirdNET ✅

Milestone Roadmap

Version Milestone Status
v0.1.0 Requirements Engineering & Specification — Complete specification of all features, tech stack, architecture, and service logic up to v1.0.0 (MVP) in .md files with clear roadmap. Repo structure, core pkg, DB, CI pipeline, ADRs, Podman as implementation foundation ✅ Done
v0.2.0 Service Infrastructure — Redis container, SilvaService base class, core.service, core.redis, core.heartbeat. All services inherit unified lifecycle. Heartbeats go live (ADR-0019). Web-Mock dev UI ✅ Done
v0.3.0 Tier 2 Container Management — Podman lifecycle, USB Detection, Profile Matching & Auto-Enrollment, Config Seeding, Log Streaming (ADR-0022), Reconciliation Loop ✅ Done
v0.4.0 Robust Audio Engine — FFmpeg Dual Stream (Raw data/raw + Processed data/processed 48kHz S16LE), Segment Promotion, Graceful Shutdown, Watchdog & Auto-Recovery ✅ Done
v0.5.0 Analysis & Backend Orchestration — Processor Service (Indexer + Janitor), Recording Registration, Data Retention Policy, Config Seeding ✅ Done
v0.5.1 Architecture & Stability Fixes — Core Data Integrity, USB Debouncing, Workspace mapping ✅ Done
v0.5.2 Core Infrastructure Upgrade — Python 3.13 adoption and runtime typing simplification ✅ Done
v0.5.3 Cloud Sync Preparatory Refactoring — Uploader wipe, storage_remotes DB drop, Test Suite Fixes ✅ Done
v0.6.0 Processor Cloud Sync — Single-target Upload Worker (FLAC compression, rclone/rsync). Internal async worker within Processor (KISS, single-target) ✅ Done
v0.7.0 Gateway (Caddy reverse proxy, HTTPS termination, internal routing) ✅ Done
v0.7.1 DB-Viewer — Database inspector, Data Export UI & Custom SQL Execution ✅ Done
v0.8.0 BirdNET — On-device avian species classification (Worker Pull via DB, ADR-0018) ✅ Current
v0.9.0 Web-Interface — Real-time status dashboard (Read+Subscribe), service control via DB + nudge 🔨 In Progress
v0.10.0 Marketing Landing Page (Astro) — Public-facing website hosted independently via GitHub Pages (Repo: kyellsen/silvasonic.de) ⏳ Planned
v1.0.0 MVP — Production-ready field deployment, stabilization (Podman Quadlets, Ansible) ⏳ Planned
v1.0.0+
v1.1.0 Icecast — Live Opus audio stream from Recorder to Web-Interface ⏳ Planned
v1.2.0 Weather — Environmental data correlation ⏳ Planned
v1.3.0 BatDetect — On-device bat species classification ⏳ Planned
v1.4.0 Metadata Export — Daily Parquet snapshot of recordings, detections, weather to cloud (Cloud-Sync extension, analytics-optimized) ⏳ Planned
v1.5.0 Tailscale — Secure remote access, VPN mesh networking ⏳ Planned

Detailed Implementation Plans

For concrete, phase-level implementation tasks see:

See Also

  • VISION.md — Core philosophy, architecture, design principles
  • README.md — Project overview, quick start
  • docs/index.md — Full technical documentation ). To preserve GitHub root visibility while supporting MkDocs, these specific duplicates indocs/` are explicitly allowed:
  • docs/AGENTS.md (Wraps ../AGENTS.md)
  • docs/ROADMAP.md (Wraps ../ROADMAP.md)
  • docs/VISION.md (Wraps ../VISION.md)
  • (Note: The main README.md requires no wrapper, as it is included directly within docs/index.md).

3. Templates (_template.md)

Each specific documentation group MUST provide a template to guarantee a consistent structure. These templates dictate the required sections. - docs/services/_template.md: For drafting planned services. - docs/user_stories/_template.md: For writing User Stories. - docs/adr/_template.md: For Architecture Decision Records. - docs/development/issues/_template.md: For tracking complex bugs or spikes. - docs/development/milestones/_template.md: For sprint planning chunks. - services/_template_readme.md: For the README.md of implemented services.

4. Docs-as-Code: Service READMEs

Implemented services are documented strictly in their own directory (services/<svc>/README.md). CRITICAL RULE 1: A Service README must NEVER paraphrase source code. Do not list API endpoints, database columns, or Python classes. The code is the Source of Truth. CRITICAL RULE 2: The "Configuration & Environment" section must ONLY list Infrastructure variables (.env / SILVASONIC_...). Dynamic Application Settings (seeded via config/defaults.yml) must NOT be documented in markdown tables. Instead, refer to config/defaults.override.yml for developer overrides as defined in the template.

A Service README is explicitly limited to the structured headers defined in services/_template_readme.md. You MUST follow this boilerplate exactly.

(Note: docs/services/<svc>.md only exists for planned services. Once a service is implemented, this file must become a 1-sentence link-stub pointing to the actual Service README).

5. Domain Documentation (docs/)

  • docs/arch/*.md: System-wide architecture patterns that span multiple services (e.g., filesystem governance, port allocation).
  • docs/user_stories/*.md: The Who and What. Focus on clear functional descriptions. Technical specifications (e.g., database fields, Redis keys, system paths) may be included in Acceptance Criteria only if necessary for exactness, but always prefer expressing the core requirement without them if possible.
  • docs/adr/*.md: ADRs are generally historical records of Past Decisions. If a major architectural path changes, prefer creating a new ADR and setting the old one to Superseded by ADR-XXX. However, completely deleting obsolete ADRs or making minor retroactive context updates is permissible in special cases to avoid repository bloat.
  • docs/hardware.md: Central configuration or technical context that cuts across multiple domains.
  • docs/deployment/*.md: Deployment processes, rollout strategies, and infrastructure guides.

6. Working Documents & Development (docs/development/)

  • docs/development/*.md: Global development guidelines (e.g., testing.md, commit.md, service_blueprint.md).
  • docs/development/milestones/*.md: Granular sprint planning chunks tracking active work. Rule: Completed milestones generally serve as historical snapshots. However, they are not rigidly immutable; it is permissible and encouraged to apply minor retroactive updates (e.g., renaming a just command or fixing broken links) to prevent confusing discrepancies.
  • docs/development/issues/*.md: Tracking specific bugs or temporary architectural investigations.
  • Scrap ideas or obsolete refactoring notes MUST go to the git-ignored .tmp/ directory or be deleted. Do not bloat the repository with dead notes.

7. AI & Automation Tooling

  • .agent/**/*.md: Internal workflow definitions and commands exclusively meant for execution by autonomous AI agents.
  • prompts/*.md: A repository of reusable, human-authored prompts. Used by developers to copy-paste (and optionally modify) instructions to AI agents.