# Net Neutrality — Technical Documentation

This directory contains detailed technical documentation for the **Net Neutrality** Discord bot
(`me.bobert:netneutrality`, version `3.0.0`).

It is intended for developers working on the codebase. It documents every major system and
subsystem, how they fit together, and the end-to-end flows that tie them.

## Table of contents

| Document | Subsystem |
|---|---|
| [architecture.md](architecture.md) | High-level architecture, startup/shutdown lifecycle, tech stack |
| [events.md](events.md) | Event handling & routing (`EventsHandler`) |
| [contexts.md](contexts.md) | Contexts — the abstraction over Discord events |
| [commands.md](commands.md) | Commands — message & slash commands, dispatch, options |
| [tasks.md](tasks.md) | Tasks — button/emoji/modal/step/built-in/persistable/scheduled tasks |
| [persistence.md](persistence.md) | Database — Hibernate/JPA, Flyway, entities, repositories, services |
| [music.md](music.md) | Music — Lavalink node & client, queue, event dispatch |
| [web-api.md](web-api.md) | HTTP Web API — internal control & introspection server |
| [threading.md](threading.md) | Threading & scheduling infrastructure |
| [utilities-and-bootstrap.md](utilities-and-bootstrap.md) | Utilities, configuration, logging, exceptions |

## How to read this documentation

Start with [architecture.md](architecture.md) for the big picture and the startup sequence.
Then read [events.md](events.md) and [contexts.md](contexts.md), because almost everything else
is triggered through a **Context** produced by the **EventsHandler**. From there, the two primary
execution paths are [commands.md](commands.md) and [tasks.md](tasks.md).

## Conventions

- Class names are given fully qualified on first mention, then by simple name.
- Database entity classes are prefixed with `O` (e.g. `OGuild`), and are documented in
  [persistence.md](persistence.md).
- Environment variables / configuration keys use the `NETNEUTRALITY_*` and `MYSQL_*` prefixes and
  are documented in [utilities-and-bootstrap.md](utilities-and-bootstrap.md).