diff --git a/README.md b/README.md
index dc994bb..1eba7fd 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,54 @@
 # Pyrom
-python/flask port of [porom](https://git.poto.cafe/yagich/porom)
+pyrom is a playful home-grown forum software for the indie web borne out of frustration with social media and modern forums imitating it.
 
-this is now the canonical implementation of porom. it's compatible with the database of porom.
+the aim is not to recreate the feeling of forums from any time period. rather, it aims to serve as a lightweight alternative to other forum software packages. pyrom is lean and "fire-and-forget"; there is little necessary configuration, making it a great fit for smaller communities (though nothing prevents it from being used in larger ones.)
 
-# License
-Released under [CNPLv7+](https://thufie.lain.haus/NPL.html).
-Please read the [full terms](./LICENSE.md) for proper wording.
+a live example can be seen in action over at [Porom](https://forum.poto.cafe/).
+
+## stack & structure
+on the server side, pyrom is built in Python using the Flask framework. content is rendered mostly server-side with Jinja templates. the database used is SQLite.
+
+on the client side, JS with only one library ([Bitty](https://bitty-js.com)) is used. for CSS, pyrom uses Sass.
+
+below is an explanation of the folder structure:
+
+- `/`
+  - `app/`
+    - `lib/` - utility libraries
+    - `routes/` - each `.py` file represents a "sub-app", usually the first part of the URL
+    - `templates/` - Jinja templates used by the routes. each subfolder corresponds to the "sub-app" that uses that template.
+    - `__init__.py` - creates the app
+    - `auth.py` - authentication helper
+    - `constants.py` - constant values used throughout the forum
+    - `db.py` - database abstraction layer and ORM library
+    - `migrations.py` - database migrations
+    - `models.py` - ORM model definitions
+    - `run.py` - runner script for development
+    - `schema.py` - database schema definition
+  - `config/` - configuration for the forum
+  - `data/`
+    - `_cached/` - cached versions of certain endpoints are stored here
+    - `db/` - the SQLite database is stored here
+    - `static/` - static files
+      - `avatars/` - user avatar uploads
+      - `badges/` - user badge uploads
+      - `css/` - CSS files generated from Sass sources
+      - `emoji/` - emoji images used on the forum
+      - `fonts/`
+      - `js/`
+  - `sass/`
+    - `_default.scss` - the default theme. Sass variables that other themes modify are defined here, along with the default styles. other files define the available themes.
+  - `build-themes.sh` - script for building Sass files into CSS
+  - `nginx.conf` - nginx config (production only)
+  - `uwsgi.ini` - uwsgi config (production only)
+
+# license
+released under [CNPLv7+](https://thufie.lain.haus/NPL.html).
+please read the [full terms](./LICENSE.md) for proper wording.
+
+# acknowledgments
+
+pyrom uses many open-source and otherwise free-culture components. see the [THIRDPARTY](./THIRDPARTY.md) file for full credit.
 
 # installing & first time setup
 ## docker (production)
@@ -68,6 +111,3 @@ $ source .venv/bin/activate
 $ python -m app.run
 ```
 
-# acknowledgments
-
-pyrom uses many open-source and otherwise free-culture components. see the [THIRDPARTY](./THIRDPARTY.md) file for full credit.