valitovgaziz
94 lines
5.2 KiB
Markdown
94 lines
5.2 KiB
Markdown
# 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
|
|
```bash
|
|
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.
|