tp/AGENTS.md

YalArba (ЯлАрба) — Tourist Aggregator

Updated: 2026-06-13 Branch: main (merged develop)

OVERVIEW

Multi-service platform: Go REST APIs + Vue3/Nuxt SPAs + Nginx reverse proxy + Certbot SSL. All deployable code lives under main_dc/. Docker Compose orchestrates ~10 services across 4 Docker networks. PostgreSQL databases, JWT auth, Gitea Actions CI/CD.

STRUCTURE

main_dc/
├── docker-compose.yml     # All services (nginx, certbot, db, apis, spas)
├── Makefile               # Per-service build/restart targets
├── .env                   # Environment variables (DO NOT COMMIT)
├── certbot/               # Let's Encrypt auto-renewal
├── nginx/                 # Reverse proxy + SSL termination
├── stubSite/              # Maintenance/placeholder page
├── valitovgaziz/          # Personal site + analytics
│   ├── html/              # Static site (valitovgaziz.ru)
│   └── analytics/         # Node.js analytics server
├── BB/                    # «Бегущий Башкир» project
│   ├── api_bb/            # Go REST API (chi + GORM)
│   └── bbvue/             # Vue3 SPA frontend
└── yalarba/               # YalArba platform
    ├── api_tp/            # Go API — auth + users (chi + GORM)
    ├── api_yal/           # Go API — accounts, objects, ratings (DDD)
    ├── api_es/            # Go API — easysite102 backend
    ├── easySite/          # Nuxt.js SPA (easysite102.ru)
    ├── serv_spa/          # Vue3 SPA (yalarba.ru frontend)
    └── tourism_types/     # Tourism classification data

KEY SERVICES

Service	Port	Tech	Description
nginx	80, 443	Nginx	Reverse proxy, SSL, static files
certbot	—	Certbot	Auto-renew Let's Encrypt certs
db	5432	PostgreSQL 15	Main DB (yalarba + easysite)
db_bb	5433	PostgreSQL 15	«Бегущий Башкир» DB
api_tp	8888	Go/Chi/GORM	Auth + user management
api_yal	8787 (internal)	Go/Chi/GORM	Accounts, objects, ratings
api_es	8088 (internal)	Go/Chi/GORM	easysite102 backend
api_bb	7777	Go/Chi/GORM	«Бегущий Башкир» backend
easysite	3000	Nuxt.js	easysite102.ru frontend
analytics	9999	Node.js	valitovgaziz.ru analytics

WHERE TO LOOK

Task	Location
YalArba auth API	main_dc/yalarba/api_tp/
YalArba business logic (DDD)	main_dc/yalarba/api_yal/internal/domain/
Main SPA (Vue3)	main_dc/yalarba/serv_spa/spa/vue/
EasySite (Nuxt)	main_dc/yalarba/easySite/easySite/
Nginx config	main_dc/nginx/nginx-ssl.conf
Docker compose	main_dc/docker-compose.yml
CI/CD workflow	.gitea/workflows/deploy.yml
Personal site	main_dc/valitovgaziz/html/

CODE MAP — api_yal (main business logic)

Symbol	Location	Role
main	main_dc/yalarba/api_yal/cmd/main.go	Entry point
router.SetupRoutes	main_dc/yalarba/api_yal/internal/router/router.go	Chi routes + middleware
domain/auth	main_dc/yalarba/api_yal/internal/domain/auth/	Login, Register, JWT, refresh tokens
domain/account	main_dc/yalarba/api_yal/internal/domain/account/	User profile CRUD
domain/object	main_dc/yalarba/api_yal/internal/domain/object/	Tourist objects CRUD
domain/rating	main_dc/yalarba/api_yal/internal/domain/rating/	Ratings (stub)
domain/comment	main_dc/yalarba/api_yal/internal/domain/comment/	Comments (stub)
domain/feetback	main_dc/yalarba/api_yal/internal/domain/feetback/	Feedback (stub)
models	main_dc/yalarba/api_yal/internal/models/	GORM models
repository	main_dc/yalarba/api_yal/internal/repository/	DB access layer
middleware	main_dc/yalarba/api_yal/internal/middleware/	Auth, admin, logging, context

CONVENTIONS

• Go: Chi router, GORM, PostgreSQL. DDD-layered (handler → service → repository).
• Auth: JWT in HttpOnly/Secure/SameSite cookies. Context key: user claims.
• Config: Environment variables via .env files, loaded by docker-compose.
• DB Migrations: Manual SQL in main_dc/yalarba/api_tp/migrations/.
• Naming: Go — short package names. Vue — PascalCase components.

CI/CD

• Trigger: Push to main branch
• Workflow: .gitea/workflows/deploy.yml
• What it does: Builds api_yal Go binary → copies to server → restarts container
• Manual deploy: Use make targets from main_dc/Makefile:

  # On server:
  make api_yal      # Full cycle: stop → pull → build → start api_yal
  make all          # Full cycle for ALL services
  make restart      # Quick restart all
  make nginx        # Rebuild nginx
  

NOTES

• .env and *.env files contain secrets — never commit.
• The old api/, spa/, migrator/ at repo root are deleted; all code is in main_dc/.
• develop branch was merged into main on 2026-06-13.
• Google Goose migrations were removed; migrations are plain SQL in api_tp/migrations/.