> For the complete documentation index, see [llms.txt](https://hayston.gitbook.io/flp-wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hayston.gitbook.io/flp-wiki/developer-documentation/architecture.md).

# Architecture and module boundaries

| Module                         | Runtime floor | Responsibility                                                              |
| ------------------------------ | ------------- | --------------------------------------------------------------------------- |
| `protocol`                     | 8             | Platform-free identity/account message contracts                            |
| `shared`                       | 8             | Dependency-free config I/O, language/fallback and small utilities           |
| `craftapi`                     | 8             | Vendored Mojang client, UUID encoding/lookup/session operations             |
| `core`                         | 8             | Classic shared routing, records, auth interfaces, anti-bot and relay models |
| `bukkit`                       | 8             | Spigot/Paper packet/early-login integration and backend auth execution      |
| `folia`                        | 21            | Hand-maintained Bukkit mirror adapted to region scheduling                  |
| `bungee`                       | 17            | Bungee identity, list persistence, forwarding and optional BungeeAuth hook  |
| `velocity`                     | 17            | Velocity identity, list persistence and forwarded declarations              |
| `fabric26_2` (`fabric/mc26_2`) | 25            | FabricProxy-Lite-forwarded identity and EasyAuth account decisions          |

These are plugin bytecode floors; the host software can require higher Java. All default builds include Fabric and run Gradle on JDK 25.

## Proxy and backend

The proxy decides verification routing, establishes Mojang/Floodgate identity, enforces network admission, owns FLP records and performs proxy-side writes/forwarding. The backend reads local auth-account state and makes the final auth-plugin action decision under the proxy's declared policies, then performs registration/login or leaves the password lock/rejects.

Neither side can replace the other's authority. The backend must not reconstruct a second identity verdict from a name, UUID shape or independent Floodgate check after consuming a valid declaration. The proxy must not claim account access succeeded before the local auth action is confirmed.

## Source boundaries

`core` does not import platform APIs, and `craftapi` does not own FLP business rules. Fabric uses `protocol` and `shared` sources rather than depending on Bukkit/Folia or proxy plugin JARs.

Bukkit and Folia have separate source files with different scheduling and platform adaptations. Check both when changing shared behavior; do not copy Bukkit sources over Folia.

## Persistence boundaries

Proxy FLP records are the source of the network list; backend AuthMe/EasyAuth stores hold local accounts. Updates to the two stores are not one database transaction, so success in one does not imply success in the other.

See also [login flow](/flp-wiki/developer-documentation/login-flow.md) and [events and extensions](/flp-wiki/developer-documentation/extensions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hayston.gitbook.io/flp-wiki/developer-documentation/architecture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.