From d3850eeca5fdb7a2d422f4fd1f20c4604c129c63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gon=C3=A7alo=20Rodrigues?= <guga@Goncalos-MacBook-Pro.local>
Date: Sat, 13 Jun 2026 13:30:20 +0100
Subject: [PATCH] docs: add architecture decisions and dashboard redesign plan
 to README

Documents agreed architectural conventions (per-app DB isolation,
path-filtered CI, secrets policy, new-app checklist) and expands
Phase 1 of the roadmap with the full dashboard UX redesign proposal.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore |  2 +-
 README.md  | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 14d70ac..78e0a1e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,7 @@
 skaffold.yaml
 
 # terraform
-*.tfstate
+*.tfstate*
 .terraform
 
 # node
diff --git a/README.md b/README.md
index b5e1b7e..ccc7f03 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,47 @@ A self-hosted personal finance dashboard running on k3s. Tracks transactions, bu
 
 ---
 
+## Architecture
+
+### Deployment
+
+GitHub Actions CI/CD. Each app has its own workflow triggered by path filters (`apps/<name>/**`) so a change to the finance service does not rebuild or redeploy unrelated apps.
+
+### Apps and services
+
+Each app lives under `apps/<name>/` and follows a shared layout:
+
+```
+apps/<name>/
+  services/
+    api/          # Go service
+  k8s/            # Kubernetes manifests (deployment, service, ingress)
+  .github/        # App-specific CI workflow (if separate from root)
+```
+
+### Database
+
+All apps share a single MongoDB instance but each app owns a **dedicated database**: `homelab_finance`, `homelab_smarthome`, etc. The `users` service writes to `homelab` and is the canonical auth source — other apps query the `users` collection directly rather than making HTTP calls between services.
+
+### Auth
+
+A shared `users` service handles registration and login. Apps that need to identify the current user resolve the session against the shared MongoDB `users` collection.
+
+### Secrets
+
+Kubernetes Secrets managed manually with `kubectl`. Secrets are never committed to git — `.gitignore` covers `*.env` and any manifest containing literal credentials.
+
+### Adding a new app
+
+Copy an existing app directory as a starting point. Conventions to follow:
+
+- Use the app's own MongoDB database (not the shared `homelab` database)
+- Add a path-filtered GitHub Actions workflow under `.github/workflows/<name>.yml`
+- Place k8s manifests under `apps/<name>/k8s/` with at minimum: `deployment.yaml`, `service.yaml`, `ingress.yaml`
+- Read the MongoDB URI and any credentials from environment variables injected by Kubernetes Secrets
+
+---
+
 ## Roadmap
 
 The main goal is to evolve from a **ledger** (records what happened) into a **financial co-pilot** (tells you what to do next, based on where you want to end up).