From 1a2287e44f1f492590a54da29b493d24cfade004 Mon Sep 17 00:00:00 2001
From: Marvin Vogt <m@rvinvogt.com>
Date: Thu, 14 Dec 2023 16:15:02 +0100
Subject: [PATCH] Add ToC and general architecture overview to README (#27)

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 721c59f..1055566 100644
--- a/README.md
+++ b/README.md
@@ -19,9 +19,63 @@
 </div>
 <br>
 
-A daemon to manage anycasted services based on status checks.
+`anycastd` is a daemon that manages services using multiple backends, each announcing the same
+service prefixes to the network as a form of load balancing, commonly know as [Anycast].
+It can be used to ensure that service prefixes are only announced when the underlying service is actually healthy, avoiding attracting traffic to service instances
+that aren't functioning correctly.
 
-# Configuration
+## Table of Contents
+
+- [Architecture](#architecture)
+  - [Services](#services)
+    - [Prefixes](#prefixes)
+    - [Health Checks](#health-checks)
+- [Configuration](#configuration)
+
+## Architecture
+
+### Services
+
+The main unit of abstraction used within `anycastd`. They combine [prefixes](#prefixes) and [health
+checks](#health-checks) to form a logical service unit that executes health checks and manages announcements.
+
+#### High Level Service Logic
+
+```
+┌─[Service]─────────────┐                        ┌──────────┐
+│                       │                   ┌──> │ HLTH CHK │
+│           ┌───────────────────────────────┤    └──────────┘
+│ IF healthy•:          │                   │    ┌──────────┐
+│     announce prefixes │                   ├──> │ HLTH CHK │
+│ ELSE:           •─────────────────────┐   │    └──────────┘
+│     denounce prefixes │               │   │    ┌──────────┐
+└───────────────────────┘               │   └──> │ HLTH CHK │
+                                        │        └──────────┘
+                                        │
+┌─[Routing Daemon]────────────────┐     │
+│ ┌──────────────────────────┐    │     │
+│ │ Prefix                   │ <────────┤
+│ │ 2001:db8::b19:bad:53/128 │    │     │
+│ └──────────────────────────┘    │     │
+│ ┌──────────────────────────┐    │     │
+│ │ Prefix                   │ <────────┘
+│ │ 203.0.113.53/32          │    │
+│ └──────────────────────────┘    │
+└─────────────────────────────────┘
+```
+
+#### Prefixes
+
+Represents a BGP network prefix that can be announced or denounced as part of a [Service]. \
+`anycastd` does not come with its own BGP implementation, but rather aims to provide abstractions
+that interface with commonly used BGP daemons.
+
+#### Health Checks
+
+Tests the components that make up a [Service] and reports whether they are healthy or not. A [Service] is considered healthy as a whole if all of it's health checks report a
+healthy status.
+
+## Configuration
 
 `anycastd` can be configured using a TOML configuration file located at `/etc/anycastd/config.toml`, or a path specified through the `--configuration` parameter.
 
@@ -49,6 +103,8 @@ The first service, aptly named "dns", simply configures a DNS resolver service t
 
 The second service, "ntp" is similar in functionality, although it's configuration is a bit more verbose. Rather than omitting values that have a preconfigured default, a [VRF] as well as a health check interval are explicitly specified.
 
+[Anycast]: https://en.wikipedia.org/wiki/Anycast
+[Service]: #services
 [FRRouting]: https://github.com/FRRouting/frr
 [Cabourotte]: https://github.com/appclacks/cabourotte
 [VRF]: https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding