oott/CLAUDE.md

Project OOTT

OOTT is an easy-to-setup network monitoring and alert system that notifies when new or unknown devices join a local area network. Two components, communicating exclusively via the backend's REST API:

• Backend (backend/): Rust, edition 2024. Runs the monitoring processes and exposes the REST API.
• Front-end (frontend/): Flutter / Dart. Configures the system and accesses stored data.

Architecture

Backend

• Entry point src/main.rs starts two Tokio threads: one for network scanning, one for the web server (serves the API and, in non-dev deployments, hosts the Flutter assets).
• State and events live in a SQLite database (oott.db by default), accessed exclusively through the data access layer (db.rs and backend/src/db/).
• Schema changes go through incremental migrations in backend/database_migrations/. Each set of structural changes is a new migration file.

Front-end

• Entry point lib/main.dart, built on Material 3.
• Must be responsive across desktop web, tablet, and phone, and ships as a native iOS/Android app (App Store / Play Store).
• All backend API access goes through utils/oott_api.dart.

Commands

Command	Purpose
cd backend && ./build.sh	Build the backend
cd backend && ./run.sh	Run the backend
cd backend && ./run_tests.sh	Run backend tests
cd backend && ./lint.sh	Run clippy (Rust linter)
cd frontend && ./run_web.sh	Run the front-end for web
cd frontend && ./run_android_emulator.sh	Boot the Android emulator (if needed) and run the front-end
cd frontend && ./run_tests.sh	Run front-end tests
dart analyze	Run the Dart linter
cd backend/data && ./update_mac_vendors --llm	Update MAC vendor list and recalculate the vendor → device-type mapping

Code style

• Rust: standard Rust style guide. Format with rustfmt; always pass --edition 2024 (e.g. rustfmt --edition 2024 <file>) to avoid spurious import-ordering changes. Avoid import aliases (use ... as ...) unless necessary.
• Dart: standard Dart style guide. Format with dart format --output show.
• All code must be as simple, human-readable, and modular as possible.

Testing & linting

• Write/update tests for every new or modified component: unit tests (backend); unit, API, and widget tests (frontend).
• After any change, run all tests and do not continue until they pass.
• Run the matching linter after adding a significant chunk of Rust or Dart.

Front-end conventions

• Use the UISnackbars component for messages that need no user action.
• Use colors from the selected theme only — never hard-code them. If a needed color isn't covered semantically by the theme, propose an addition to the project's theme extension.
• Prefer built-in Flutter/Material components. Build a custom one only when it's genuinely a better fit, and in that case present the custom-vs-built-in trade-offs to the human and get confirmation first.
• Keep new screens/widgets/dialogs consistent with existing similar widgets and with Material 3 guidance (button emphasis hierarchy, action placement, theming).

Workflow

• Commit directly to main by default; don't create branches (single-developer project).
• Always commit TODO.md when it changes, without ticking items — it's fully human-managed.
• Keep formatter changes: never revert a file just because the formatter reformatted it (even files you didn't otherwise touch), and add such changes to the current commit. Revert only if the reformatting actually introduces a bug.

Must / must not

• When adding a new API endpoint, always wire it into the OpenAPI generation.
• NEVER add or commit .env files or any files containing secrets (passwords, API keys, etc.).