# AGENTS.md

## Repo overview

Docker Compose hosting for 4 websites (yalarba.ru, begushiybashkir.ru, easysite102.ru, valitovgaziz.ru).  
All infrastructure lives under `main_dc/`. Root `package.json` is vestigial — do not use it.

## Directory structure

```
main_dc/
  docker-compose.yml        -- single compose file orchestrating everything
  Makefile                  -- the primary dev/ops interface; use `make` not raw docker
  .env                      -- shared env: domains, email, api_es port
  BB/api_bb/                -- Go REST API (GORM+Chi), port 7777, DB: db_bb (5433)
  BB/bbvue/                 -- Vue 3 + Vite frontend for begushiybashkir.ru
  yalarba/api_tp/           -- Go REST API (GORM+Chi), port 8888, DB: db (5432)
  yalarba/api_es/           -- Go REST API (GORM+Chi), port 8088, DB: db (5432)
  yalarba/api_yal/          -- Go REST API (GORM+Chi), port 8787, DB: db (5432)
  yalarba/easySite/easySite/ -- Nuxt 4 SPA for easysite102.ru
  yalarba/serv_spa/spa/vue/  -- Vue 3 + Vite SPA for yalarba.ru
  valitovgaziz/analytics/   -- Node.js (Express) analytics server, port 9999
  valitovgaziz/html/         -- static HTML for valitovgaziz.ru
  nginx/                    -- nginx with automatic HTTP↔HTTPS switching
  certbot/                  -- Let's Encrypt cert management
  stubSite/                  -- placeholder site while building
```

## Developer commands (always run from `main_dc/`)

| Command | What it does |
|---|---|
| `make all` | Full cycle: down → git pull → build --no-cache → up -d → watch |
| `make <svc>` | Full cycle for one service, e.g. `make api_bb`, `make nginx`, `make es`, `make analytics` |
| `make bbvue` | Rebuild Vue frontend (calls `npm run build` in `BB/bbvue/`) |
| `make vue_bb` | git pull + npm cache clean + bbvue build + watch |
| `make wn` | `watch -n2 docker ps` — monitor containers |
| `make bb_db` | `psql -U postgres -d bb_db` inside db_bb container |

All `build_*` targets use `--no-cache`.  
All full-cycle targets follow: `stop_<svc> → git → build_<svc> → start_<svc> → wn`.

## Frontend dev (outside compose)

```bash
cd main_dc/BB/bbvue && npm run dev      # Vite dev server
cd main_dc/BB/bbvue && npm run lint     # ESLint --fix
cd main_dc/BB/bbvue && npm run format   # Prettier --write src/

cd main_dc/yalarba/serv_spa/spa/vue && npm run dev   # Vite dev (yalarba SPA)

cd main_dc/yalarba/easySite/easySite && npm run dev  # Nuxt dev
cd main_dc/yalarba/easySite/easySite && npm run build # Nuxt build
```

## Service quirks

- **Nginx SSL**: `switch-config.sh` is all-or-nothing — HTTPS only activates when *every* domain has a cert. Until then, SSL port redirects back to HTTP.
- **`yalarba/serv_spa/spa/`**: Dockerfile is incomplete (build stage only, no runtime). The `spa/vue/` package.json includes express/pg deps despite being a Vite SPA — likely unused or legacy. The nginx compose mounts `yalarba/serv_spa/spa/vue/dist`.
- **`api_yal`** is the only container that runs as non-root. Runs on port 8787.
- **`api_es`** port is configurable via `API_ES_APP_PORT` in `.env` (default 8088). All other API ports are hardcoded.
- **Databases**: `db` (port 5432) is shared between api_tp, api_es, api_yal. `db_bb` (port 5433) is dedicated to api_bb.
- **GORM auto-migration**: All Go APIs use GORM auto-migrate at startup — no manual migration tooling.
- **Keycloak** referenced in Makefile targets but absent from docker-compose.yml — likely not deployed.
- **`api_yal/testrunner`**: standalone Go test runner binary (not containerized), for running integration test suites.

## Docs convention

READMEs and documentation are primarily in Russian. See `documentation/` for Makefile, Docker, restart, and LLM info docs.