what2watch/README.md

125 lines
5.5 KiB
Markdown
Raw Normal View History

2023-06-22 23:39:41 +00:00
# *Untitled Project for the Social Consumption of Media*
2023-06-11 22:42:17 +00:00
2023-07-11 00:18:58 +00:00
*(last updated 2023-07-10)*
2023-06-11 22:42:17 +00:00
2023-07-11 00:18:58 +00:00
![what to watch](what2watch_logo.png)
2023-06-12 00:06:27 +00:00
2023-06-22 23:39:41 +00:00
This is the main repository for UPSCM, formerly "Witch Watch", formerly "What2.Watch",
etc. etc. UPSCM is intended to primarily support the following things as an end user:
2023-06-11 22:50:59 +00:00
* keep track of things you want to watch, eg, TV shows, movies, videos, etc.
2023-06-11 22:53:18 +00:00
* including type of thing, whether or not it's private, whether you watched it already, etc.
2023-06-11 22:50:59 +00:00
* keep track of people you want to watch those things with
* easy to take all your data with you, no lock-in
2023-06-11 22:42:17 +00:00
As an operator, it's meant to be as simple as possible:
2023-06-11 22:50:59 +00:00
* 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
2023-06-11 22:42:17 +00:00
As a developer, it's meant to be easy to work on:
2023-06-11 22:50:59 +00:00
* Pure Rust backend
2023-06-11 22:53:18 +00:00
* [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)
2023-06-11 22:50:59 +00:00
* Simple front end
2023-06-11 22:53:18 +00:00
* currently unstyled hand-written HTML with no javascript!
* barely there!
* a good place for contributing!
2023-06-11 22:42:17 +00:00
## 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
2023-06-22 23:39:41 +00:00
a thin veneer over and runner for application, defined inside a [`lib`](src/lib.rs) crate. The lib
2023-06-11 22:42:17 +00:00
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
2023-07-11 00:18:58 +00:00
├── bin
│   ├── import_omega.rs
│   └── import_users.rs
├── db_id.rs
2023-06-11 22:42:17 +00:00
├── db.rs
├── generic_handlers.rs
2023-07-11 00:18:58 +00:00
├── import_utils.rs
2023-06-11 22:42:17 +00:00
├── 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/`:
2023-06-11 22:50:59 +00:00
* `db.rs`: interfacing with sqlite
2023-06-11 22:53:18 +00:00
* (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)
2023-06-11 22:50:59 +00:00
* `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
2023-07-11 00:18:58 +00:00
* `bin/`: tools for importing data
2023-06-11 22:42:17 +00:00
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/`:
2023-06-11 22:50:59 +00:00
* `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
2023-06-11 22:42:17 +00:00
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:
2023-06-11 22:50:59 +00:00
* `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
2023-06-11 22:42:17 +00:00
2023-06-22 23:39:41 +00:00
It's likely that there will be `css/` and `javascript/` directories in the future. Likewise code for
2023-06-11 22:42:17 +00:00
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,
2023-06-11 22:50:59 +00:00
* finishing the `watches` module, allowing adding things to watch to the system and to your own watchlist
* full-text-search with Tantivy
2023-06-11 22:53:18 +00:00
* realistically, you need this as soon as you can start adding data to it
2023-06-22 23:39:41 +00:00
* endpoints for inviting friends to watch stuff with you
2023-06-11 22:42:17 +00:00
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
2023-06-11 22:50:59 +00:00
supporting that inside this. And way, way down the line, I might want to add ActivityPub for
fediverse compatibility.