Add developer overview

.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
     rev: 24.8.0
     hooks:
     -   id: black
-        exclude: migrations/
+        exclude: ^(src/.*/migrations|docs/conf.py)
 -   repo: https://github.com/twisted/towncrier
     rev: 24.8.0
     hooks:

docs/conf.py

@@ -50,6 +50,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
+    'sphinx.ext.graphviz',
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "djangodocs",

docs/development.rst

@@ -5,6 +5,7 @@ Development
 
 .. toctree::
 
+   development/birdseye-view
    development/notes
    development/management-commands
    development/howtos

docs/development/birdseye-view.dot

@@ -0,0 +1,32 @@
+digraph overview {
+    compound=true;
+
+    subgraph cluster_server {
+        style = rounded;
+        label = "server"
+        destination1[label="destination 1"];
+        destination2[label="destination 2"];
+        destination3[label="destination 3"];
+    }
+
+    glueservice1[label="glue service 1"];
+    source1[label="source 1"];
+
+    source1 -> glueservice1 -> destination2 [lhead=cluster_server];
+
+    subgraph cluster_source2 {
+        style = rounded;
+        label = "source 2"
+        glueservice2[label="glue service 2"];
+    }
+
+    glueservice2 -> destination2 [lhead=cluster_server];
+
+    exterior1[shape="none"][style="invis"][label=""];
+    exterior2[shape="none"][style="invis"][label=""];
+    exterior3[shape="none"][style="invis"][label=""];
+
+    destination1 -> exterior1;
+    destination2 -> exterior2;
+    destination3 -> exterior3;
+}

docs/development/birdseye-view.rst

@@ -0,0 +1,65 @@
+=================
+A bird's eye view
+=================
+
+.. graphviz:: birdseye-view.dot
+
+Sources
+=======
+
+A source pushes incidents to the argus server via the API. Subsequent changes
+to those incidents are made by posting events to them. An incident has a field
+``incident_source_id`` for storing an id, for changing an already existing
+incident by adding an event.
+
+Glue-service
+------------
+
+A glue-service runs independently of the argus server. It sits between a source
+and the argus server and translates an incident from the source to the API. The
+``incident_source_id`` for the incident is copied from the source if available
+or otherwise handled by the glue-service.
+
+The glue-service can either be built in to the source, or be completely
+standalone and pull changes from the source before it pushes them on.
+
+Agent
+-----
+
+An agent can change existing incidents (by adding events) or create new
+incidents by analyzing already existing incidents and events.
+
+It is standalone.
+
+Frontend
+========
+
+The frontend fetches a list of incidents according to a user-created filter. It
+allows the user to create such filters, to set up notification profiles
+using these filters, and to set up destinations to be used in the profiles.
+
+Notification system
+===================
+
+A user has one or more notification profiles.
+
+A notification profile is used by the server for sending notifications about
+a chosen subset of the incidents. It consists of one or more filters, one or
+more timeslots (for which periods of the day a profile is valid) and one or
+more destinations.
+
+Destination
+-----------
+
+A destination is a plugin to argus server. It stores its config in the
+"DestinationConfig"-model. See :doc:`/writing-plugins`.
+
+Server
+======
+
+The server receives incidents from sources, provides access to the accumulated
+list of incidents via API, and matches incidents to notification profiles.
+Matched incidents are sent to the destinations listed in the profiles.
+
+There is a non-API admin-interface for the registration of sources and admin
+users.

pyproject.toml

@@ -102,6 +102,7 @@ exclude = '''
     | buck-out
     | build
     | dist
+    | docs/conf.py
   )/
   | src/.*/migrations
 )