Component Design

A dendrite server is made from a number of components each a cluster of separate processes. Each component handles a distinct subset of the Matrix APIs.

Components should generally have the following directory layout:

src/github.com/matrix-org/cmd/<component-name>/main.go  # The binary for running a process for the component.
src/github.com/matrix-org/<component-name>/api/         # The structs and internal HTTP query APIs 
                                                        # this component exposes to other components
src/github.com/matrix-org/<component-name>/types/       # The types used internally by this component.
src/github.com/matrix-org/<component-name>/storage/     # Implementation of storage used by this component.
src/github.com/matrix-org/<component-name>/storage/<table-name>.go # Schema and queries for a single table.
src/github.com/matrix-org/<component-name>/consumers/   # Consumers for internal kafka messages.
src/github.com/matrix-org/<component-name>/query/       # Implementation of internal HTTP query APIs.
src/github.com/matrix-org/<component-name>/routing/     # Entry point for external HTTP matrix APIs.

New components must be placed in a directory under https://github.com/matrix-org/dendrite/tree/master/src/github.com/matrix-org/dendrite. They must produce at least one binary file and be documented with a README at the top-level of its directory.

New components may read from or write to Kafka logs. The expected input/output structs must be put in an api package. New components may also expose internal HTTP APIs. These APIs must also be put in the api package. Together, this forms the API for the component which other components can make use of.

Components can share types/structs between each other by putting them inside https://github.com/matrix-org/dendrite/tree/master/src/github.com/matrix-org/dendrite/common. Be sparing about this: do not prematurely add code "just-in-case". Pure functions that aren't dendrite specific should be added to https://github.com/matrix-org/gomatrixserverlib.

New components may want to read or write to a database. This database should be Postgres 9.5+ unless there is an agreed upon reason not to. SQL statements should exist in .go files under a storage package. Each table should correspond directly to one *_table.go file, unless there is a compelling reason not to (e.g 2 very tightly coupled tables where the statements don't make sense without the context of the other table).

Components must expose a prometheus /metrics HTTP listener using https://github.com/prometheus/client_golang and a /debug HTTP listener using https://golang.org/pkg/net/http/pprof/.