chore: adding docs

2026-10-07 15:05:48 +02:00 · 2026-10-07 15:05:48 +02:00 · 81c5112409
commit 81c5112409
parent 23816d00f7
39 changed files with 7257 additions and 2 deletions
--- a/data/docs/go-first.md
+++ b/data/docs/go-first.md
@ -0,0 +1,197 @@
+<!-- go-doc:generated:begin source=go-first signature=b2d9663478587eb442ff68c6d7e66369 generated=2026-10-07 09:29 UTC -->
+# go-first
+
+> **URPI** — Web Application & Backend Development Experts > Live at: [https://www.urpi.be](https://www.urpi.be)
+
+|  |  |
+| --- | --- |
+| Module | github.com/dnoulet/go-first · go 1.23 · 12 Go files |
+| Endpoints | 0 endpoints |
+| Components | 0 component directories |
+| Tests | none detected |
+| Go lines | 1383 lines |
+
+> Everything between the generated markers is rewritten by every sync. Notes written outside the markers are kept.
+
+## For Users
+
+### What this application does
+
+> **URPI** — Web Application & Backend Development Experts > Live at: [https://www.urpi.be](https://www.urpi.be)
+
+The project ships its own README at `README.md`, which is the long form of this page. The three audience tabs split the same facts three ways so you only read the part that concerns you.
+
+### Reading this in go-doc
+
+Open the page and pick the tab that matches you:
+
+- **User** — you use the finished application. This section is all you need.
+- **Operator** — you run it. Configuration, ports and deployment notes are under that tab.
+- **Developer** — you integrate with it or change it. The API and layout tables are under that tab.
+
+The feedback panel stores a note per audience, tagged with your badge, so operators and developers can see which audience raised it.
+
+### Where the original documentation lives
+
+This project already carries 4 Markdown documents. They stay in the project repository: this page points at them instead of copying them, so there is always exactly one copy of the truth.
+
+| Document | Size |
+| --- | --- |
+| `README.md` | 9681 bytes |
+| `docs/API.md` | 8052 bytes |
+| `docs/DEPLOYMENT.md` | 9465 bytes |
+| `docs/DEVELOPMENT.md` | 11918 bytes |
+
+---
+
+## For Operators
+
+### Running it locally
+
+The root Makefile defines 30 targets:
+
+- `make build-backend`
+- `make build-frontend`
+- `make cert-renew`
+- `make cert-status`
+- `make check-deps`
+- `make ci-build`
+- `make ci-install`
+- `make ci-test`
+- `make clean-all`
+- `make db-migrate-create`
+- `make db-migrate-down`
+- `make db-migrate-up`
+- `make deploy-staging`
+- `make dev-backend`
+- `make dev-frontend`
+- `make generate`
+- `make install`
+- `make lint-backend`
+- `make lint-frontend`
+- `make logs`
+- `make release-major`
+- `make release-minor`
+- `make release-patch`
+- `make restart`
+- `make start`
+- `make status`
+- `make stop`
+- `make test-backend`
+- `make test-frontend`
+- `make version`
+
+### Local containers
+
+The compose file defines these services:
+
+| Service | Image | Published ports |
+| --- | --- | --- |
+| app | built locally | internal only |
+| postgres | `postgres:16-alpine` | internal only |
+| redis | `redis:7-alpine` | internal only |
+| nginx | `nginx:alpine` | internal only |
+
+### Image
+
+`Dockerfile` builds from `golang:1.23-alpine`, `node:20-alpine`, `alpine:3.20` in stages: backend-builder, frontend-builder and exposes 8080.
+
+### Configuration
+
+Every environment variable found in the source or in a `.env` file:
+
+| Variable | Example | Found in |
+| --- | --- | --- |
+| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000,http://localhost:5173,http://127.0.0.1:3000,http://127.0.0.1:5173` | .env file |
+| `DATABASE_HOST` | `localhost` | .env file |
+| `DATABASE_NAME` | `go_first_dev` | .env file |
+| `DATABASE_PASSWORD` | `postgres` | .env file |
+| `DATABASE_PORT` | `5432` | .env file |
+| `DATABASE_SSL_MODE` | `disable` | .env file |
+| `DATABASE_USER` | `postgres` | .env file |
+| `EMAIL_FROM_ADDRESS` | `noreply@localhost` | .env file |
+| `EMAIL_FROM_NAME` | `URPI Local` | .env file |
+| `EMAIL_PASSWORD` | — | .env file |
+| `EMAIL_SMTP_HOST` | — | .env file |
+| `EMAIL_SMTP_PORT` | `587` | .env file |
+| `EMAIL_USERNAME` | — | .env file |
+| `FRONTEND_BUILD_PATH` | `./web/dist` | .env file |
+| `FRONTEND_SPA_FALLBACK` | `true` | .env file |
+| `JWT_EXPIRES_IN` | `24` | .env file |
+| `JWT_REFRESH_EXPIRES_IN` | `168` | .env file |
+| `JWT_SECRET` | `local_development_secret_key_change_in_production` | .env file |
+| `LOGGING_FORMAT` | `console` | .env file |
+| `LOGGING_LEVEL` | `debug` | .env file |
+| `LOGGING_OUTPUT` | `stdout` | .env file |
+| `REDIS_DB` | `0` | .env file |
+| `REDIS_HOST` | `localhost` | .env file |
+| `REDIS_PASSWORD` | — | .env file |
+| `REDIS_PORT` | `6379` | .env file |
+| `SERVER_HOST` | `0.0.0.0` | .env file |
+| `SERVER_MODE` | `debug` | .env file |
+| `SERVER_PORT` | `8080` | .env file |
+
+### Network surface
+
+Ports referenced across the project: `5432`, `8080`.
+
+### Deployment artefacts
+
+No Helm chart was found, so deployment is expected to be plain Docker or a managed platform.
+
+### Operations documentation that already exists
+
+Read these in place rather than duplicating them here:
+
+- `docs/DEPLOYMENT.md` — Deployment Guide — go-first / URPI
+
+> No HTTP route registrations were detected. If this is a server, the API table is incomplete — check for routes built dynamically.
+
+---
+
+## For Developers
+
+### Module layout
+
+- go.mod — module github.com/dnoulet/go-first, go 1.23, 5 direct and 26 indirect dependencies
+
+### HTTP API
+
+No route registrations were detected, which is expected for a CLI, a library or a worker.
+
+### Direct dependencies
+
+- `github.com/gin-gonic/gin` v1.10.0
+- `github.com/google/uuid` v1.6.0
+- `github.com/joho/godotenv` v1.5.1
+- `github.com/rs/zerolog` v1.33.0
+- `gopkg.in/yaml.v3` v3.0.1
+
+### Directory map
+
+| Directory | Files | Lines | Likely purpose |
+| --- | --- | --- | --- |
+| `web/` | 37 | 2366 | frontend assets |
+| `internal/` | 11 | 1266 | unimportable application internals |
+| `docs/` | 3 | 0 | project documentation |
+| `deploy/` | 2 | 316 | deployment manifests |
+| `cmd/` | 1 | 117 | binary entry points |
+
+### Languages
+
+- **JSON** — 4 files, 6107 lines
+- **TypeScript** — 27 files, 2262 lines
+- **Markdown** — 4 files, 1784 lines
+- **Go** — 12 files, 1383 lines
+- **YAML** — 4 files, 540 lines
+- **out** — 1 file, 354 lines
+- **conf** — 1 file, 185 lines
+- **CSS** — 1 file, 161 lines
+- **Shell** — 1 file, 131 lines
+- **JavaScript** — 2 files, 94 lines
+
+### Developer documentation that already exists
+
+- `docs/API.md` — API Documentation — go-first / URPI
+- `docs/DEVELOPMENT.md` — Development Guide — go-first / URPI
+<!-- go-doc:generated:end -->