# Daemon Architecture
> The graphd lifecycle — startup, watching, persistence, and shutdown.
[Source](https://open.nxtsoft.io/docs/cgraph/daemon)

`graphd` is what makes the graph *warm*. Instead of rebuilding on every query, it
holds the graph in memory, watches the tree, and folds in changes as they happen.

## Lifecycle

_The daemon's lifecycle_

```text
start ──> build initial graph ──> serve + watch ──┐
                                        ^          │  edits: incremental fold-in
                                        └──────────┘  branch switch: full rescan
                                        │
              idle-timeout / shutdown ──┴──> re-persist to cgraph-out/ ──> exit
```

## Startup

Launch the daemon against a project root:

**start the daemon**

```bash
graphd --root /path/to/project
```

On first run it builds the initial graph (seconds for a typical tree), then
begins serving operations and watching the tree.

## Watching

While running, the daemon watches the project and folds source edits into the
graph incrementally — usually within a couple of seconds. A large batch, such as
a branch switch, collapses into a single full rescan rather than thousands of
tiny updates. Pass `--no-watch` to disable watching; updates then happen only via
explicit `update` operations. See [Incremental Updates](/docs/cgraph/incremental-updates)
for the details.

## Flags

```text
graphd --root PATH [--idle-timeout SECONDS] [--no-watch]
```

| Flag | Meaning |
| --- | --- |
| `--root` | Project tree to index and watch. |
| `--idle-timeout` | Shut down after this many idle seconds. |
| `--no-watch` | Don't watch the tree; update only on explicit ops. |

The default `--idle-timeout` value is not stated in the public README and is
left pending rather than guessed.

## Persistence and shutdown

Incremental state is re-persisted to `cgraph-out/` in the background and on
shutdown, so restarting the daemon resumes from the last graph instead of a cold
rebuild. Shut it down explicitly with the client:

**shut down**

```bash
cgraph-client shutdown
```