From f2ab3e0498d9d9eacc28f6de22cd19442ee6ba2c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20Doma=C5=84ski?= <pi.domanski@gmail.com>
Date: Wed, 8 Apr 2026 12:02:35 +0200
Subject: [PATCH] readme

---
 Readme.md                                | 62 ++++++++----------------
 doc/install/docker-compose.yml           | 26 ++++++++++
 env.template => doc/install/env.template |  0
 3 files changed, 47 insertions(+), 41 deletions(-)
 create mode 100644 doc/install/docker-compose.yml
 rename env.template => doc/install/env.template (100%)

diff --git a/Readme.md b/Readme.md
index 30ea324..21fad52 100644
--- a/Readme.md
+++ b/Readme.md
@@ -2,51 +2,31 @@
 
 Simple API for food diary application. It uses FastAPI and async postgres.
 
-## Usage
+## Overview and key points of configurating and deploying API
 
-Simply build docker images with:
+API is maily suited for being run as docker container, either via docker compose or inside kubernetes/openshift, tho no configuration for those are provided in this repository. Example `docker-compose.yml` for deployment is provided in `doc/install/docker-compose.yml`.
 
-```bash
-docker-compose build
-```
+Configuration is passed through env variables. Sample configuration is provided in `doc/install/env.template`.
 
-And then start them up with:
+Database migrations are handled through alembic. For ease of use, `doc/install/Makefile` provides formula for `make migrate` that upgrades database to head migration.
 
-```bash
-docker-compose up -d
-```
+## Development
 
-Create `.env` file with configuration by copying template `env.template`. *You have to generate secret keys!* They are stored under `SECRET_KEY` and `REFRESH_SECRET_KEY`
-in `.env` file and both could be generated with `openssl rand -hex 32`.
+Project architecture design was summarized in `ARCHITECTURE.md`, altho summary was generated with usage of AI for now so might not be perfect or informative ;)
 
-To initialize database exec:
+Overall, project consists of:
 
-```bash
-docker-compose exec api bash -c python -m fooder --create-tables
-```
-
-## Deployment
-
-For deployment delete:
-
-```
-    volumes:
-      - ./fooder:/opt/fooder/fooder
-```
-
-and
-
-```
-    command: "uvicorn fooder.app:app --host 0.0.0.0 --port 8000 --reload"
-```
-
-lines from `docker-compose.yml`. This line makes app reload everytime code changes and is only recommended for development purposes.
-
-I highly recommend using reverse proxy like nginx for HTTPS.
-
-## Documentation
-
-When api is started using docker, by default it runs on 8000 port on local machine (it can be changed within `docker-compose.yml` file). Swagger documentation is available
-on `http://0.0.0.0:8000/docs` when you start the app.
-
-Alternatively you can visit [my own instance of the API docs](https://fooderapi.domandoman.xyz/docs).
+- `fooder/alembic` - alembic python scripts, migrations, autogenerated
+- `fooder/context` - context with authorized session, repositories
+- `fooder/domain` - sqlalchemy domain definitions
+- `fooder/controller` - controllers for domain models, controllers hold logic linked with only one model
+- `fooder/repository` - repositories for domain models, again single repo per model, altho because of joins there are some methods that touch more than one model
+- `fooder/model`- pydantic models
+- `fooder/view` - fastapi routes
+- `fooder/utils` - utils
+- `fooder/app` - fastapi app definitions
+- `fooder/db` - sqlalchemy database core functionality
+- `fooder/recaptcha` - recaptcha implementation
+- `fooder/exc` - exceptions live there
+- `fooder/router` - fastapi main router
+- `fooder/settings` - pydantic-settings for app
diff --git a/doc/install/docker-compose.yml b/doc/install/docker-compose.yml
new file mode 100644
index 0000000..fabcdca
--- /dev/null
+++ b/doc/install/docker-compose.yml
@@ -0,0 +1,26 @@
+networks:
+  fooder:
+    driver: bridge
+
+services:
+  database:
+    restart: unless-stopped
+    image: postgres
+    networks:
+    - fooder
+    env_file:
+      - .env
+
+  api:
+    restart: unless-stopped
+    image: registry.domandoman.xyz/fooder/api
+    build:
+      dockerfile: Dockerfile
+      context: .
+    platform: linux/amd64
+    networks:
+    - fooder
+    env_file:
+      - .env
+    ports:
+      - "8000:8000"
diff --git a/env.template b/doc/install/env.template
similarity index 100%
rename from env.template
rename to doc/install/env.template