BirdLense Hub — Documentation
Version 0.3.2 (source of truth: repo root
VERSION) · OpenAPI: YAML spec · Interactive: Redoc · Published docs: gfermoto.github.io/BirdLense-Hub
Welcome. This folder is the single source of truth for operators, integrators, and contributors. Use it to run the stack, fix issues, extend the project, or repurpose content for a website, wiki, or blog (see OVERVIEW).
Start in three paths
Pick what matches you — you can read the rest as reference.
| Path | You want to… | Go to |
|---|---|---|
| Run | Install Docker, connect cameras, go live | OVERVIEW (context) → INSTALL → SCENARIOS |
| Integrate | Frigate, BirdNET, MQTT, HA, Telegram | SCENARIOS → CONFIGURATION |
| Build & ship | Hacks, tests, releases | Repository layout → LOCAL_DEV → TESTING → Contributing |
Product & reference
| Topic | English | Russian |
|---|---|---|
| Short description (GitHub About, press) | SHORT_DESCRIPTION.md | RU |
| Project story (for landing & articles) | OVERVIEW | RU |
| Install & deploy | INSTALL | RU |
| Recipes & workflows | SCENARIOS | RU |
| Config keys & env | CONFIGURATION | RU |
| Terms (Hub, Frigate, merge, …) | GLOSSARY | RU |
| Feature matrix & API hints | FEATURES | RU |
| System design | ARCHITECTURE | RU |
| HTTP API narrative | API · OpenAPI Redoc | RU · Redoc RU |
| Versioning | VERSIONING | RU |
| Server deploy checklist | DEPLOY_SERVER | RU |
Security & operations
| Topic | Document |
|---|---|
| Access & passwords | ACCESS_CONTROL · RU |
| Threats & hardening | SECURITY |
| Recover broken config | RECOVERY_CONFIG · RU |
| When something fails | TROUBLESHOOTING · RU |
Quality & tooling
| Topic | Document |
|---|---|
| Unit, API, E2E, post-deploy checks | TESTING · RU |
| Automated verification log (releases / critical fixes) | VERIFICATION · RU |
| MCP (Model Context Protocol — external AI assistants) | MCP_SETUP · RU |
ML, data & roadmap
| Topic | English | Russian |
|---|---|---|
| Model training (EU/US) | TRAINING | RU |
| Datasets & scripts | DATASETS | RU |
| Versioning & releases | VERSIONING | RU |
| Direction / backlog | ROADMAP | RU |
Project meta
| Topic | Document |
|---|---|
| Repository layout (onboarding) | REPOSITORY_LAYOUT · RU |
| How docs are written (placeholders, i18n, site reuse) | Documentation · RU |
| Security analysis (technical) | SECURITY · RU |
| Secrets rotation (production ops) | SECRETS_ROTATION · RU |
| Open-source release checklist | OPEN_SOURCE_PREP · RU |
| Governance & external review | GOVERNANCE · RU |
| Issues, board & roadmap process | ROADMAP § Triage · RU; root CONTRIBUTING |
| GitHub CLI setup (personal repo) | GITHUB_SETUP_GH · RU |
| Wiki + CI reports (Summary / Artifact / optional Wiki push) | WIKI_AUTOMATION · RU |
| Translation status | I18N_STATUS |
Site sections ↔ files (keep in sync with mkdocs.yml) |
SITE_MAP · RU |
| MkDocs site (build & GitHub Pages) | Documentation § Static documentation site |
| Historical notes | archive/README (in repo; excluded from MkDocs build) |
Quick commands (from repo)
| Goal | Command |
|---|---|
| Local stack | cd app && make local → http://localhost:8085 |
| Web tests | cd app && make test-web |
| Telegram proxy autorotate | make proxy-rotation-install (status: make proxy-rotation-status) |
| Full doc index above | You are here ✓ |
| Preview static doc site | pip install -r requirements-docs.txt && mkdocs serve (details) |
For server deploy patterns, see INSTALL.