major CRUD refactor

This is the start of a large refactor to move all entity CRUD (create,
read, update, delete) model/database code into it's own file.

HACKING has been updated with an overview of what happens in each file.

Next steps:
- split rev (and sub-table) insertion in to db_rev_insert and make
  create/update generic
- inserts should be batch (vector) by default
- move all other entities into this new trait framework
- bypass api_server wrappers and call into CRUD from api_wrappers for
  entity ops (should be a big cleanup)

1 files changed, 34 insertions, 0 deletions

diff --git a/rust/HACKING.md b/rust/HACKING.md
index a399164c..622a4b5a 100644
--- a/rust/HACKING.md
+++ b/rust/HACKING.md
@@ -1,4 +1,38 @@
 
+## Code Structure
+
+Almost all of the rust code is either auto-generated or "glue" between the
+swagger API spec on one side and the SQL schema on the other.
+
+- `./migrations/*/up.sql`: SQL schema
+- `./src/database_schema.rs`: autogenerated per-table Diesel schemas
+- `./src/database_models.rs`: hand- and macro-generated Rust structs matching
+  Diesel schemas, and a small number of row-level helpers
+- `./src/database_entity_crud.rs`: "struct-relational-mapping"; trait
+  implementations of CRUD (create, read, update, delete) actions for each
+  entity model, hitting the database (and building on `database_model` structs)
+- `./src/api_server.rs`: one function for each API endpoint, with rust-style
+  arguments and return types. mostly calls in to `database_entity_crud`.
+- `./src/api_wrappers.rs`: hand- and macro-generated wrapper functions, one per
+  API endpoint, that map between API request and return types, and
+  rust-idiomatic request and return types (plus API models).
+- `./fatcat-api`: autogenerated API models and endpoint types/signatures
+- `../fatcat-openapi2.yaml`: 
+
+When deciding to use this structure, it wasn't expected that either
+`api_wrappers.rs` or `database_models.rs` would need to hand-maintained; both
+are verbose and implemented in a very mechanical fashion. The return type
+mapping in `api_wrappers` might be necessary, but `database_models.rs` in
+particular feels unnecessary; other projects have attempted to completely
+automate generation of this file, but it doesn't sound reliable. In particular,
+both regular "Row" (queriable) and "NewRow" (insertable) structs need to be
+defined.
+
+## Test Structure
+
+- `./tests/test_api_server.rs`: Iron (web framework) level raw HTTP JSON
+  request/response tests of API endpoints.
+
 ## Updating Schemas
 
 Regenerate API schemas after editing the fatcat-openapi2 schema. This will, as