# Operating Modes and Source of Truth

## Page Purpose

Use this page to choose and enforce your source of truth policy (built-in integrations vs custom source of truth) before production changes.

Need definitions for terms on this page? See the [Glossary](glossary.md).

```{mermaid}
flowchart TD
    A[Choose Source of Truth] --> B{Using built-in CRM/NMS integration?}
    B -->|Yes| C[Built-in Integrations Mode]
    B -->|No| D{Generating files from your own scripts/systems?}
    D -->|Yes| E[Custom Source of Truth Mode]
    D -->|No| F[Manual Files Mode]
    C --> G[Integration sync jobs own file refresh]
    E --> H[External script pipeline owns persistence]
    F --> I[Direct file maintenance; best for small networks]
```

LibreQoS supports two first-class operating modes.

## Built-in Integrations (Recommended for Most Operators)

In this mode, your CRM/NMS is the source of truth and LibreQoS integration jobs produce shaping inputs.

Key behavior:
- `ShapedDevices.csv` is regenerated by integration sync cycles.
- `network.json` overwrite behavior depends on integration settings (for example `always_overwrite_network_json`).
- Direct manual edits may be overwritten on the next scheduler refresh.

## Custom Source of Truth

In this mode, your own scripts/systems generate `network.json` and `ShapedDevices.csv`.

Key behavior:
- Your external workflow owns persistence.
- WebUI edits are valid for quick operational changes.
- Permanent changes should be made in your external source of truth workflow.

## Mode Declaration Checklist (Before Go-Live)

1. Pick one primary source of truth.
2. Confirm which system can write production shaping inputs.
3. Confirm scheduler refresh behavior and overwrite cadence.
4. Document your hotfix workflow (WebUI, external editor, or both).
5. Do not maintain competing edits in multiple systems for the same objects.

## Topology and Mode Expectations

- Single-interface (on-a-stick) and VLAN-heavy designs are valid, but require explicit queue/interface planning and careful validation after changes.
- Integration mode is best when you want CRM/NMS-driven topology and subscriber lifecycle data to own shaping inputs.
- If you need strict custom topology behavior not represented by integration output, use custom source of truth mode and keep ownership explicit.

See:
- [Advanced Configuration Reference](configuration-advanced.md)
- [Troubleshooting](troubleshooting.md)

If you are running built-in integrations, continue to [CRM/NMS Integrations](integrations.md).

## Related Pages

- [Configure LibreQoS](configuration.md)
- [CRM/NMS Integrations](integrations.md)
- [Advanced Configuration Reference](configuration-advanced.md)