Developer

These pages are for maintainers and contributors. They explain WG Free Mesh internals, module boundaries, and collaboration rules.

If you only want to deploy and use the system, start with Guide and Usage. Read this section before changing the backend, frontend, client, database schema, MQTT protocol, or MCP capabilities.

Reading Order

1. Architecture: understand the main processes and components.
2. Project Structure: understand source directories, runtime data, and ownership boundaries.
3. Backend: understand where business rules live.
4. Database: understand SQLAlchemy, Alembic, and snapshots.
5. Frontend: understand why the frontend does not duplicate backend rules.
6. Client: understand wfm-agent and wfmctl.
7. Events: understand SSE event boundaries.
8. MQTT Protocol: understand the control channel between backend, EMQX, and clients.
9. API Contract: understand response shape, errors, and download tokens.
10. Collaboration: read this before making broad changes.

By Task

Task	Start with	Then check
Add a console page	Frontend	Backend, API Reference, Realtime Reference
Add or change a backend API	API Contract	Backend, Errors, MCP Reference
Change database fields or tables	Database	Data Model, Snapshots
Change dynamic client control	Client	MQTT Protocol, MQTT Messages, Client Lifecycle
Change mesh generation or AllowedIPs	Backend	Quick Mesh Reference, Data Model
Change WireGuard / AmneziaWG parameters	Client	Protocols, MQTT Messages
Change MCP capabilities	API Contract	MCP Reference, Security
Change deployment or environment variables	Architecture	Environment, Docker Deploy, Reverse Proxy

Before Changing Code

The core rule is simple: the backend and database are the source of truth. The frontend displays and calls. The client executes local actions.

Update documentation when changing:

• API paths, request fields, response fields, or error codes.
• Database tables, migrations, or snapshot content.
• MQTT topics, payloads, ACKs, or online state rules.
• MCP resources, tools, permissions, or audit behavior.
• Docker, environment variables, reverse proxy, or deployment layout.
• Client commands, install behavior, or local file layout.