# Architecture

NeoAgent is a Node.js service with Flutter clients. The server owns
authentication, model access, agent execution, tools, integrations, automation,
memory, persistence, and real-time state.

## Main components

```text
Flutter clients and messaging channels
                |
        Express + Socket.IO
                |
  agents / AI engine / tasks / integrations
                |
 runtime backends / SQLite / agent data
```

### Server

`server/index.js` creates the application and service managers. Express routes
handle HTTP boundaries and delegate behavior to services. Socket.IO publishes
run progress, approvals, messages, device state, and operational updates.

The server uses CommonJS. Routes should remain thin; business logic belongs in
`server/services/`.

### Clients

The Flutter codebase produces the web operator interface, Android client,
desktop clients, and Android launcher build. `MainController` is the root
application state object. Platform behavior is implemented through conditional
bridge files and native Android code where required.

### Persistence

NeoAgent uses one `better-sqlite3` database instance. It stores users, agents,
settings, conversations, runs, tasks, integration connections, memory,
recordings, health data, permissions, and operational state.

Runtime files live outside the package source under `NEOAGENT_HOME`. Schema
changes are applied through the migration layer rather than ad hoc service SQL.

### Execution runtimes

Browser and terminal tools normally use the per-user isolated runtime. A user
can select a paired Chrome extension for browser work or a paired desktop
client for shell and desktop control. Android remains a host ADB capability.

## Subsystem guides

- [Agent run lifecycle](agent-run-lifecycle.md)
- [Memory architecture](memory-architecture.md)
- [Runtime and tool execution](runtime-and-tools.md)
- [Agents, automation, and triggers](automation-architecture.md)
- [Integrations and messaging](integrations-architecture.md)
- [Clients and device bridges](clients-and-devices.md)
- [Persistence and migrations](persistence.md)
- [Development and testing](development.md)
