some docs

README.md

@@ -11,9 +11,12 @@ laseca is a social bitcoin to cash exchange, implemented as a webapp.
   + Run `npm install`
   + You can now start the app in a container by running `npm run start:container` (and shut it down with `npm run stop:container`).
 * Running
+  + Copy the `.env.dist` file into `.env` and set any values you like.
   + The app will run in a single container, with a Postgres database, a caddy webserver and the nodejs app.
   + Note that the container doesn't come with a volume for Postgres: default behaviour is to start from scratch every time you create the container, delete everything every time you delete the container.
   + The docker image launches the nodejs app with nodemon, so changes to the code will be available immediately.
+  + The Postgres database is reachable from the host, so you can use your favourite SQL client to access it.
+  + You can format with `npm run format` and lint with `npm run lint`.
 
 ## How to deploy
 
@@ -25,6 +28,11 @@ The (hypothetical) approach is to:
 * Configure them all nice and stuff so they work together and have a reasonable production set up.
 * Set up the node app with systemd so it runs proper.
 
+## Docs
+
+You can find documentation under `docs/`.
+
 ## Other
 
-* You can format with `npm run format` and lint with `npm run lint`.
+* `other/branding` contains brand assets of laseca.
+* `other/nostr-brand-assets` contains some nostr-related open source icons, logos, etc.

docs/README.md

@@ -0,0 +1,28 @@
+# laseca docs
+
+This is the documentation of laseca. It's targeted at devs and operators.
+
+## Overview
+
+laseca is a simple webapp. It follows a pretty standard setup:
+* A postgres database holds the data of the application.
+* A NodeJS+ExpressJS app serves both UI pages and API endpoints for the app.
+* We suggest serving with Caddy, but any web server should do.
+
+## Sessions, users and authentication
+
+All users of laseca must have a nostr identity. Nostr identities consist on a public-private key pair.
+
+Upon visiting any page, the requester gets a session cookie in the form of a UUID7 record. Sessions can be authenticated, which allow the users to enter the app itself. Unauthenticated users can only visit the login page and some exceptional pages, if they do have the URL.
+
+Signups are not public: individual invites are provided, each identified with a UUID7. Users use invites by visiting an invite page and using it to signup with their Nostr keypair. The invite URLs are public, but since they hold a UUID7 in them, only people that have been given the URL can truly go in.
+
+When the user signs up or logs in, they are asked to answer a challenge with their Nostr web extension. Successfully signing the challenge with their key identifies them with it, and also increases the privileges of the session.
+
+Should a cookie expire, the user will get a new one, and will have to go through the login again to ensure it has enough privileges.
+
+Invites can be created through the CLI.
+
+## CLI 
+
+The app comes with a CLI designed to be used by the laseca instance operator. The CLI is highly privileged and can perform powerful actions. Do not provide anyone with access to it.