add some documentation for top-level modules

src/main.rs

@@ -3,14 +3,50 @@ use sqlx::postgres::PgPoolOptions;
 use sqlx::{migrate, PgPool};
 
 mod conf;
+
+/// Core data types used throughout the entire app.
 mod core;
+
+/// Data sources for repositories.
+///
+/// Data sources are the interfaces between repositories and an underlying
+/// storage layer, such as Postgres or Redis.  Each data source is only
+/// responsible for a single storage engine, and a repository may have multiple
+/// data sources of different preferences.
 mod data;
+
+/// Asynchronous background workers.
 mod job;
+
+/// Database models and validation.
 mod model;
+
+/// The central interface between data storage and the rest of the app.
+///
+/// This module contains all _Repositories_, which are the central interface
+/// between the data storage/management code and the rest of the server.
+/// They act as a full layer of abstraction to keep the rest of the app
+/// completely agnostic to the internals of how storage, including caching,
+/// is implemented.
+///
+/// Any data that the rest of the app needs access to or wishes to store must
+/// travel through an interface provided by a repository.  This makes them
+/// perfect gatekeepers for enforcing validation, which is why APIs that store
+/// data will typically be implemented as generics that require an
+/// `Into<Sane<T>>` (where `T` is the model structure for that database table).
+///
+/// Internally, repositories act on several _Data Sources_.
+/// See the [`data`] module for more information.
 mod repo;
+
+/// HTTP request handlers.
 mod route;
+
 mod state;
+
+/// Miscellaneous little helpers.
 mod util;
+
 use crate::core::*;
 use conf::Config;