# Getting Started

## The App Object

The central entry point is `App`. It wires together all components:

```python
from brinkhaustools.common import App

app = App(name="my-service")
app.start()
```

`App` creates these components by default:

| Attribute       | Component              | Default config                     |
|-----------------|------------------------|------------------------------------|
| `app.shutdown`  | `ShutdownHandler`      | always created                     |
| `app.logging`   | `LoggingHelper`        | `data/logs/`                       |
| `app.settings`  | `Settings`             | `data/settings/settings_main.json` |
| `app.diagnosis` | `SelfDiagnosisEngine`  | always created                     |
| `app.status`    | `StatusEngine`         | always created                     |
| `app.heartbeat` | `HeartbeatEngine`      | 300s default timeout               |
| `app.version`   | `VersionInformation`   | `helper/version.json`              |
| `app.fleet`     | `StatusMonitor`        | `fleetManagementData/config.json`  |

Pass `None` to skip any component:

```python
app = App(
    name="my-service",
    settings_path=None,       # no settings file
    fleet_config_path=None,   # no fleet reporting
    version_file=None,        # no version tracking
)
```

## Reading Settings

```python
timeout = app.settings.get(["expert", "timeout"], default=300)
# or with dot-notation:
timeout = app.settings.get("expert.timeout", default=300)
```

## Reporting Diagnostics

```python
app.diagnosis.notify(code=1001, message="Database unreachable", critical=True)
# Later, when resolved:
app.diagnosis.clear(code=1001)
```

## Heartbeat Watchdog

```python
app.heartbeat.register("main-loop", timeout_sec=60)

while not app.shutdown.is_shutdown():
    app.heartbeat.register("main-loop", timeout_sec=60)  # refresh
    do_work()
```

## Fleet Management

To report status and diagnostics to the BrinkhausFleetManager, create
`fleetManagementData/config.json`:

```json
{
    "fleetmanagement": {
        "customer_name": "my-customer",
        "machine": "machine-01",
        "broker": "fleet.brinkhaus-gmbh.de",
        "heartbeat_interval_sec": 60,
        "token": "fmt_..."
    }
}
```

The token is created in the FleetManager UI (*Customers → Manage Tokens*).

With the config in place, `App` automatically starts the fleet monitor:

```python
app = App(name="my-service")
app.start()  # heartbeats + diagnosis bridging start automatically
```

Any diagnostics reported via `app.diagnosis.notify(...)` are automatically
forwarded to the FleetManager every 60 seconds.

See [Fleet Management API reference](api/common.md#fleet-management) for
standalone usage, environment overrides, and endpoint details.

## Adding a REST Server

Install the `rest` extra, then:

```python
from brinkhaustools.rest import RestServer

server = RestServer(app=app, port=8080)
server.start()

app.wait()
```

## Graceful Shutdown

```python
# Block until SIGTERM/SIGINT:
app.wait()

# Or check in a loop:
while not app.shutdown.is_shutdown():
    app.shutdown.sleep(1)  # interruptible sleep

# Trigger programmatically:
app.shutdown.trigger()
```
