add readme

README.md

@@ -0,0 +1,115 @@
+# *Untitled Social Media Consumption Project*
+
+*(last updated 2023-06-11)*
+
+This is the main repository for USMCP, formerly "Witch Watch", formerly "What2.Watch",
+etc. etc. USMCP is intended to primarily support the following things as an end user:
+ - keep track of things you want to watch, eg, TV shows, movies, videos, etc.
+  + including type of thing, whether or not it's private, whether you watched it already, etc.
+ - keep track of people you want to watch those things with
+ - easy to take all your data with you, no lock-in
+
+As an operator, it's meant to be as simple as possible:
+ - single binary that can be copied and deployed easily
+ - local database (sqlite) and associated files, easily copied and inspected
+ - pervasive use of universally unique IDs allows simple merges from other instances
+
+As a developer, it's meant to be easy to work on:
+ - Pure Rust backend
+  + [Axum](https://github.com/tokio-rs/axum) with Tokio for async http routing
+  + [SQLx](https://github.com/launchbadge/sqlx) for talking with the database
+  + [Askama](https://github.com/djc/askama) for templates
+  + [Tantivy](https://github.com/quickwit-oss/tantivy) for full and fuzzy text searching (PLANNED)
+ - Simple front end
+  + currently unstyled hand-written HTML with no javascript!
+  + barely there!
+  + a good place for contributing!
+
+## Overview of the code
+
+### Rust
+
+Like most Rust projects, it's broken up into at least two distinct crates, a [`bin`](src/main.rs) crate that acts as
+a thin veneer over and runner for the main entry point inside the [`lib`](src/lib.rs) crate. The lib
+crate exposes a couple public functions and datastructures used in the bin crate and in testing, but
+otherwise mostly brings some lib-crate-wide types into the `crate::` scope and defines the `app`
+method that returns an [Axum::Router](https://docs.rs/axum/latest/axum/struct.Router.html), and
+currently has all the HTTP route declarations.
+
+The full `src` directory currently looks like:
+
+``` text
+src
+├── db.rs
+├── generic_handlers.rs
+├── lib.rs
+├── login.rs
+├── main.rs
+├── signup.rs
+├── templates.rs
+├── test_utils.rs
+├── users.rs
+├── util.rs
+└── watches
+    ├── handlers.rs
+    ├── mod.rs
+    └── templates.rs
+```
+
+The simple modules (that is, ones that are a single file without anything from submodules being
+exposed to anywhere else outside themselves) are all under `src/`:
+
+ - `db.rs`: interfacing with sqlite (this has an inlined external crate for managing login sessions
+   with sqlite, which takes up most of the lines in the file, but should be considered mostly external)
+ - `generic_handlers.rs`: callback definitions for serving things like redirects to `/`
+ - `login.rs`: error types and handlers for login/logout routes
+ - `signup.rs`: error and response types, and handlers, for signup route
+ - `templates.rs`: Askama templates for the simple modules
+ - `users.rs`: definitions and trait implementations for `User`s
+ - `util.rs`: misc useful functions
+
+Tests for those modules are kept as submodules inside them.
+
+Compound modules, those that are a `mod.rs` file inside a subdirectory of `src/`, will broadly
+follow the example of `src/watches/`:
+
+ - `watches/mod.rs`: data types and impls for the thing to watch (a `Watch`)
+ - `watches/templates.rs`: Askama templates for `Watch`-related pages and objects
+ - `watches/handelers.rs`: callbacks and their error types for handling requests to `Watch`-related routes
+
+Tests for each are kept as submodules inside each submodule, as with the simple modules.
+
+In general, all templates will be available directly under the `crate::` scope, as you can see in
+the `use` statements in `lib.rs`, but handlers are not.
+
+### Non-Rust
+
+At the project root, next to the `src/` directory, are two other directories:
+
+ - `migrations/`: SQL files that define the schemas and add things like indexs and triggers
+ - `templates/`: HTML templates used by one or more Askama templates to control presentation
+
+It's likely that there will be `css/` and `javascript` directories in the future. Likewise code for
+helping with deploying or monitoring.
+
+## Development goals
+
+Currently, I think the backend is 40-60% "complete", where 100% would mean that all use cases
+outlined at the top are working. The front end is approximately unstarted.
+
+The current development priorities are, in order from most to least important,
+
+ - finishing the `watches` module, allowing adding things to watch to the system and to your own watchlist
+ - more front-end templates to support the `watches` operations
+ - full-text-search with Tantivy
+  + realistically, you need this as soon as you can start adding data to it
+
+After that, it will be a focus on the front end, and possibly a Flutter/Dart app for mobile. For the
+web client, I'm leaning toward something like [HTMx](https://htmx.org/docs/#introduction) but am not
+against other lightweight javascript solutions.
+
+And finally, things like commandline tools to do things like reset passwords or delete accounts, or
+otherwise interact with the database outside of the main app. And then, OAuth or OIDC support. Down
+the line, I want to experiment with implementing
+[Backchannel](https://www.inkandswitch.com/backchannel/) for decentralized and social identity and
+supporting that inside this.