The LogForge Core service is the central control plane that discovers Docker containers, streams their telemetry, and exposes APIs consumed by the Alert Engine and Notifier. It runs alongside two supporting containers: a React frontend (`logforge-frontend`) and an optional Watchtower-based auto-updater (`logforge-autoupdate`). The backend is shipped as source-available code so teams can audit or extend it for maximum transparency (see the [logforge-core repository](https://github.com/log-forge/logforge-core)).

## Responsibilities
- Discover running containers through the Docker socket and keep an in-memory registry up to date.
- Collect logs and metadata, exposing them via HTTP and WebSocket endpoints for the dashboards.
- Manage user-defined container groups (stored in SQLite) so rules and views can target related services.
- Provide REST APIs that the Alert Engine and Notifier use for container snapshots, groups, config, and health.
- Broadcast container and group changes in real time to any connected UI or automation client.

## Architecture
- **logforge-backend**: Python FastAPI application with direct `/var/run/docker.sock` access. Handles discovery, APIs, WebSockets, and persistence.
- **logforge-frontend**: Vite/React UI that calls the backend APIs and listens for WebSocket updates.
- **logforge-autoupdate** (optional): Watchtower derivative that tracks container updates when `AUTO_UPDATE=true`.
- All services share the `logforge-network` bridge network; UI ports bind to `127.0.0.1` by default for local access only.

## Key APIs (partial)
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/containers` | GET | Returns the cached container list plus monitored groups. |
| `/groups` | GET/POST/PATCH/DELETE | CRUD operations for container groups. |
| `/config/preferences` | GET/POST | UI preferences (timezone, etc.). |
| `/config/filters/add-keyword` | POST | Manage core keyword filters. |
| `/health` | GET | Summarises container counts, rule counts, and DB status. |

Refer to `logforge/backend/app/routes` for the full FastAPI router definitions.

## WebSocket channels
- `/ws/logs/{container_name}`: streams live logs for an individual container.
- `/ws/updates/{type}`: unified feed for config, alerts, containers, or `all` update types.
- `/ws/updates/alerts/{container}`: per-container alert stream (newer alternative to the unified channel).
- `/ws/updates/containers`: broadcasts container and group snapshots whenever the registry changes.

## Group management workflow
1. Users create or edit groups via the Core UI; changes hit `/groups` on the backend.
2. Groups persist in the Core SQLite database (`logforge_core_data` volume) using the `Group` and `GroupMembership` tables (`app/models/settings.py`).
3. When groups or containers change, the backend rebuilds the monitored list and pushes updates to WebSocket subscribers.
4. The Alert Engine listens to the same WebSocket feed, filters out groups without monitored containers, and surfaces the result in its rule builder scope pickers.

## Interaction with other services
- **Alert Engine**: Polls `/containers` and `/groups`, receives WebSocket updates, and calls `/alerts/ingest` to push alert metadata back into Core.
- **Notifier**: Core exposes configuration endpoints; notifier destinations are managed independently but Core references the notifier container for test sends.
- **Auto-updater**: Optional service that restarts containers when new images are available, respecting the `AUTO_UPDATE` flag.

## Persistence and volumes
- `logforge_core_data`: stores the Core SQLite database (container registry, groups, UI settings).
- The backend writes only to this volume; application code lives in the container image.

## Security considerations
- The backend has full Docker control through the socket; protect it with network boundaries or a `docker-socket-proxy` if you need fine-grained API whitelisting.
- UI ports bind to loopback by default; use a reverse proxy with TLS and authentication when exposing the dashboard outside the host.
- Keep credentials (SMTP, webhooks, tokens) in environment variables or Docker secrets rather than the compose file.

## Related documentation
- [Installation & Setup](Setup.md)
- [Automation Rule Playbooks](Automation-Playbooks.md)
- [Security & Hardening](Security.md)
- [Notifier & Integrations](Notifier-Integrations.md)