replica-omnisciente/.aurelio/DIRECTORY_GUIDE.md

Repository Directory Guide

This file helps AI coding agents navigate the repository structure efficiently. Updated: 2026-04-08

Repository Layout

smart-device-firmware/
│
│  ── FIRMWARE (ESP-IDF project — root-level, do NOT move) ──
│
├── main/                      ← Main application component
│   ├── main.cpp               ← app_main() entry point
│   ├── hardware_config.h      ← Pin assignments for all HW versions
│   ├── fsm/                   ← Finite state machine (10 states)
│   ├── power/                 ← Power manager (sleep, PIR, wake)
│   └── tasks/                 ← FreeRTOS tasks (wifi, aws, lcd, model, etc.)
├── components/                ← Custom ESP-IDF components
│   ├── bq25895/               ← Battery charger driver (v2.8)
│   ├── pcal9538a/             ← I2C IO expander driver (v2.8)
│   ├── captive_portal/        ← WiFi provisioning portal
│   ├── data_storage/          ← NVS-based persistent storage
│   ├── lcd_driver/            ← ST7701S LCD driver
│   ├── lcd_ui/                ← LVGL UI + fonts + images
│   ├── model/                 ← TFLite ML model pipeline (audio→inference)
│   ├── session_manager/       ← Shower session tracking
│   ├── wifi_manager/          ← WiFi connect/provisioning
│   ├── psram_diagnostics/     ← PSRAM health monitoring
│   ├── recovery_watchdog/     ← Watchdog for crash recovery
│   ├── system_info/           ← System metrics reporting
│   ├── certs/                 ← AWS IoT claim certificate
│   └── common/                ← Shared logging macros
├── managed_components/        ← Auto-managed (IDF component manager)
├── CMakeLists.txt             ← Root project CMake
├── sdkconfig                  ← Active build config
├── sdkconfig.defaults         ← Default config values
├── partitions.csv             ← Flash partition table
├── dependencies.lock          ← Component version lock
│
│  ── SCRIPTS & TOOLING ──
│
├── scripts/                   ← Build, CI, and fleet tools
│   ├── build.py               ← Build firmware
│   ├── build_tool.py          ← Unified build interface (configure/build/flash/monitor)
│   ├── configure.py           ← Run menuconfig
│   ├── flash.py               ← Flash to device
│   ├── erase_flash.py         ← Erase device flash
│   ├── monitor.py             ← Serial monitor
│   ├── setup_env.sh           ← Shell aliases for IDF tools
│   ├── check_all_patterns.py  ← Master regression pattern checker
│   ├── check_firmware.py      ← Firmware integrity checks
│   ├── check_regressions.sh   ← Shell-based regression checker
│   ├── install_hooks.sh       ← Git hooks installer
│   ├── regression_checks/     ← 8 pattern checkers (psram, ota, audio, etc.)
│   ├── test_suites/           ← HIL test suite orchestration
│   ├── ci/                    ← CI/CD analysis tools
│   │   └── fetch_ci_logs.py   ← Download + parse GitHub Actions logs
│   ├── fleet/                 ← Fleet management
│   │   ├── fleet_flash/       ← Multi-device flash tool
│   │   ├── live_verification/ ← Live device health checks
│   │   └── setup_runner.sh    ← Self-hosted runner setup
│   └── codegen/               ← Model/audio codegen
│       ├── generate_*.py      ← DCT, DFT, mel bin range generators
│       └── query_influx.py    ← InfluxDB query tool
│
│  ── TESTING ──
│
├── test/                      ← All test infrastructure
│   ├── host/                  ← Host-based unit tests (Unity + CMake)
│   │   ├── CMakeLists.txt     ← Test build system
│   │   ├── mocks/             ← ESP-IDF mock headers and stubs
│   │   └── tests/             ← Test source files (test_*.c)
│   ├── hil/                   ← Hardware-in-the-loop tests (pytest)
│   ├── target/                ← Target-specific test source
│   └── apps/                  ← ESP-IDF test applications
│       ├── fsm_integration_test/
│       └── model_task_integration_test/
│
│  ── AI AGENT INFRASTRUCTURE ──
│
├── .agent/                    ← AI agent configuration and tools
│   ├── mcp/                   ← MCP (Model Context Protocol) servers
│   │   ├── savearth-mcp/      ← savearth MCP server (Python/FastMCP)
│   │   │   ├── server.py      ← Unified MCP server (18 tools: device + telemetry + CI)
│   │   │   ├── README.md      ← MCP setup and configuration guide
│   │   │   └── ...
│   │   └── setup.sh           ← Proxmox LXC deployment script
│   ├── skills/                ← Agent skills (specialized capabilities)
│   │   ├── firmware-log-analyzer/  ← Analyze device logs for bugs
│   │   ├── telemetry-analyzer/     ← Query InfluxDB telemetry
│   │   ├── mcp-builder/            ← Build new MCP servers
│   │   └── skill-creator/          ← Create new skills
│   ├── workflows/             ← Agent workflows (slash commands)
│   │   ├── atomic-commits.md  ← Git commit best practices
│   │   ├── brainstorm.md      ← Requirements discovery
│   │   ├── document.md        ← Documentation generation
│   │   ├── research.md        ← Technical discovery
│   │   ├── resume-session.md  ← Restore previous session
│   │   ├── save-current-session.md
│   │   ├── save-as-new-session.md
│   │   ├── start-new-session.md
│   │   └── unit-test.md       ← Unity test automation
│   ├── plans/                 ← Agent planning documents
│   ├── research/              ← Technical feasibility studies
│   ├── chat-sessions/         ← Session persistence for context resumption
│   ├── bugfixes/              ← Bug fix documentation
│   ├── scratch/               ← Research code and experiments
│   └── DIRECTORY_GUIDE.md     ← This file
├── AGENTS.md                  ← Top-level agent instructions
│
│  ── BUILD ENVIRONMENTS ──
│
├── containers/                ← Docker/Podman/LXC build environments
│   ├── debian/                ← Debian-based (primary, ~2GB)
│   ├── alpine/                ← Alpine-based (minimal, ~500MB)
│   ├── rockylinux/            ← Rocky Linux-based (~1.5GB)
│   ├── lxc/                   ← LXC system container setup
│   ├── container-tool.py      ← Container management tool
│   └── run-container.sh       ← Container convenience script
│
│  ── DOCUMENTATION ──
│
├── docs/                      ← Project documentation
├── README.md                  ← Project README
│
│  ── CI/CD ──
│
├── .github/workflows/         ← GitHub Actions workflows
│   ├── unit-tests.yml         ← Host unit tests + coverage
│   ├── regression_prevention.yml ← Static analysis + pattern checks
│   ├── hil-tests.yml          ← Hardware-in-the-loop tests
│   └── release.yml            ← Release builds
│
│  ── EPHEMERAL DATA (git-ignored, local only) ──
│
├── ci-logs/                   ← Downloaded CI/CD logs (auto-created by tools)
├── logs/                      ← Raw device serial logs (auto-created by monitoring)
├── build/                     ← ESP-IDF build output
└── .cache/                    ← IDE caches

Directories to IGNORE When Searching

When scanning for firmware source code, skip these directories:

• managed_components/ — third-party libraries, not our code
• build/ — compiled output
• .cache/ — IDE index
• ci-logs/ — ephemeral CI data
• logs/ — ephemeral device logs
• **/__pycache__/ — Python bytecode cache
• .git/ — version control

Key Entry Points

Task	Path
Build firmware	scripts/build_tool.py or scripts/build.py
Flash device	scripts/flash.py
Run unit tests	test/host/ → cmake && ctest
Run pattern checks	scripts/check_all_patterns.py
Fetch device logs	See AGENTS.md → Diagnostic Commands
MCP server	.agent/mcp/savearth-mcp/server.py
Container build	containers/container-tool.py