CLAUDE.md

1# AI agent rules for Firezone
2 
3## Summary
4 
5Firezone is a zero-trust access platform built on top of WireGuard.
6The data plane components are built in Rust and reside in `rust/`.
7The control plane components are built in Elixir and reside in `elixir/`.
8 
9## Data plane architecture
10 
11At the core of the data plane resides a shared library called [`connlib`](../rust/libs/connlib).
12It combines ICE (using the `is` library) and WireGuard (using the `boringtun` library) to establish on-the-fly tunnels between Clients and Gateways.
13The entry-point for the data plane is [`Tunnel`](../rust/libs/connlib/tunnel) which acts as a big event-loop combining three components:
14 
15- A platform-specific TUN device
16- A sans-IO state component representing either the Client or the Gateway
17- A platform-specific UDP socket
18 
19Packets from IO sources (TUN device and UDP socket) are passed to the state component, resulting in a UDP or IP packet.
20The state component also manages ICE through the [`snownet`](../rust/libs/connlib/snownet) library, so some UDP traffic is handled internally and does not yield an IP packet.
21 
22These three components are split into multiple threads and connected via bounded channels:
23 
24- 1 thread for reading from the TUN device
25- 1 thread for writing to the TUN device
26- 1 thread for handling IPv4 UDP traffic with 1 task each for sending / receiving
27- 1 thread for handling IPv6 UDP traffic with 1 task each for sending / receiving
28- 1 task on the "main" thread that holds the state and reads / writes from and to the channels connecting to the IO threads
29 
30## Coding guidelines
31 
32For guidelines on generating or reviewing specific parts of the codebase, check for an `AGENT.md` file in the corresponding sub-directory.
33For example, for Rust code, check `rust/AGENT.md`; for Elixir code, check `elixir/AGENT.md`, etc.
34 
35## Code review guidelines
36 
37- Assume that code compiles and is syntactically correct.
38- Focus on consistency and correctness.
39- Give extra special attention to any security-sensitive code, such as cryptographic operations, authentication logic, and access control mechanisms.
40 
41## Code contributions
42 
43- Use [Conventional Commits](https://www.conventionalcommits.org/) for PR titles. The static analysis workflow enforces a maximum length of 64 characters (see `.github/workflows/_static-analysis.yml`).
44- Keep PR descriptions minimal.
45  - Concise prose explaining what is changing **at a high level** and why.
46  - Do not describe the code changes that can be seen in the diff again in prose.
47  - Do not add a test plan section.
48  - Do not include links to the Claude session.
49  - Link relevant PRs / issues using `Related: #XXXX`
50  - Take inspiration from https://cbea.ms/git-commit; the squash-merged PRs will have the PR description as a commit message on main.
51    However, do not add hard line-breaks to the PR description itself.
52    GitHub will take care of that when merging.
53- Run static analysis locally before committing.
54- If a required tool is missing, check whether `mise.toml` declares it and install it via `mise` rather than through another package manager.
55