tp/AGENTS.md

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

Generated: 2026-06-12 Commit: 165d5a5 Branch: main

OVERVIEW

Go REST API backend (chi router + GORM + PostgreSQL) with docker-compose orchestration. SPA frontend via Nginx reverse proxy + Certbot. Goose for DB migrations. JWT auth via HttpOnly cookies.

STRUCTURE

./
├── api/                    # Go backend service
│   ├── cmd/main.go         # Entry point
│   ├── src/
│   │   ├── configs/        # Server + DB config structs
│   │   ├── initializers/   # Chi routing + GORM DB init
│   │   ├── models/         # GORM models (User, Essence, Contact, Point)
│   │   ├── rt/             # Route handlers grouped by domain
│   │   │   ├── auth/       # Login, Register, JWT middleware
│   │   │   ├── admin/      # Admin-only endpoints
│   │   │   ├── prf/        # Profile (stub)
│   │   │   └── srch/       # Search (stub)
│   │   └── storages/psql/  # Global *gorm.DB var
│   └── Dockerfile
├── migrator/               # Goose migration runner
│   └── migrations/         # Timestamped SQL migrations
├── spa/                    # Nginx + static HTML landing + certbot
│   ├── index.html          # Landing page (Russian)
│   └── data/nginx/         # Nginx config
├── docker-compose.yaml     # services: db, api, migrator, spa, certbot
├── Makefile                # build, run, clean, test
└── .env                    # Environment variables (DO NOT COMMIT)

WHERE TO LOOK

Task	Location	Notes
Add API route	api/src/initializers/Routing.go + api/src/rt/	Register handler in Routing.go; create handler in rt/ subdir
Add DB model	api/src/models/	GORM struct with json + gorm tags; UUID PKs
Add migration	migrator/migrations/	Goose format: timestamp_description.sql
Auth logic	api/src/rt/auth/	JWT in HttpOnly cookie; claims in request context
DB access	api/src/storages/psql/psql.go	Global PSQL_GORM_DB *gorm.DB
Config/env vars	.env → os.Getenv() in code	Config structs in api/src/configs/

CODE MAP

Symbol	Type	Location	Role
main	func	api/cmd/main.go:16	Entry: calls InitChiRouting + InitDBconnection
InitChiRouting	func	api/src/initializers/Routing.go:21	Sets up chi router, middlewares, all routes
InitDBconnection	func	api/src/initializers/PGQL_DB.go:14	GORM Postgres connection, sets psql.PSQL_GORM_DB
PSQL_GORM_DB	var	api/src/storages/psql/psql.go:5	Global DB handle
Login	func	api/src/rt/auth/Login.go:21	Validates creds, issues JWT cookie
Register	func	api/src/rt/auth/Registr.go:54	Validates input, hashes password, creates user
AuthMiddleware	func	api/src/rt/auth/authMiddleware.go:11	JWT cookie validation middleware
AuthAdminMiddleware	func	api/src/rt/auth/authAdminMiddlware.go:11	JWT + role=admin check
User	struct	api/src/models/user.go:5	GORM model: id, name, email, password, phone, role
Claims	struct	api/src/models/authDataStructs.go:15	JWT claims: email, phone, role

CONVENTIONS

• Naming: Go package names are short abbreviations (auth, prf, srch, admin). File names in PascalCase.
• DB: GORM with UUID PKs (AutoIncrement:false). Goose for migrations with timestamp prefixes.
• Auth: JWT stored in HttpOnly/Secure/SameSite cookie. Role stored in claims. Context key is "email".
• Config: All config via os.Getenv(), no config files. .env loaded by docker-compose.
• Logging: log/slog structured logging.
• Errors: http.Error() for simple errors. JSON-encoded validationError struct for validation.
• Password: bcrypt cost 14. Max password length 72 (bcrypt limit).
• Role defaults: Empty role on registration → "user".

ANTI-PATTERNS (THIS PROJECT)

• os.Exit(2) on DB failure — kills entire process, no graceful shutdown
• Duplicate JWT parsing logic between authMiddleware.go and authAdminMiddlware.go
• authAdminMiddlware.go has typo in filename ("Middlware")
• AuthUserMiddleware.go in prf/ is a dead stub (always 401)
• Global mutable state (PSQL_GORM_DB, package-level jwtKey)
• HTTPS enforced on JWT cookies but HTTP port 80 exposed — mismatch in dev
• AGENTS.md in .gitignore because it previously contained secrets — credentials belong in .env only

COMMANDS

make          # docker compose up (default)
make build    # docker compose build
make run      # docker compose up
make clean    # docker builder prune
make test     # go test ./api/src/auth/... -v
make tc       # go test -cover

NOTES

• .env contains real secrets — never commit. The .gitignore entry for AGENTS.md was added because it previously held credentials. Remove that .gitignore line once this file is clean.
• Profile and Search handlers are stubs (empty bodies).
• Docker services depend on each other: db → api → migrator → spa+certbot.
• Goose migration GOOSE_DBSTRING in .env must match PG credentials.