Files
kotosoft-id/AI_SYSTEM_DOCS.md
T
2026-05-04 11:14:30 +03:00

177 lines
5.3 KiB
Markdown

# Kotosoft ID - AI System Documentation
This document is written for AI assistants (and developers) that need a fast, practical understanding of this repository.
## What this system is
Kotosoft ID is an identity and OAuth service with:
- a Go backend (`kotosoft-id-backend`) exposing OAuth and user/profile APIs,
- a Next.js frontend (`kotosoft-id-frontend`) handling login/consent UI and token cookies,
- PostgreSQL + Redis as dependencies.
Main use cases:
- OAuth2 Authorization Code + PKCE login flow,
- access/refresh token issuance and refresh,
- user profile management,
- consent management,
- role/permission ("positions") administration.
## Repository structure
- `kotosoft-id-backend`: Go API service (Gin, pgx, redis, JWT logic)
- `kotosoft-id-frontend`: Next.js app (App Router, server actions)
- `docker-compose.yml`: production-style compose wiring backend + frontend images
- `.drone.yml`: CI/CD pipeline (backend tests, frontend lint, image build/push, deploy)
## Runtime architecture (high-level)
1. Frontend starts OAuth initiation (`/api/auth/initiate`) and creates PKCE verifier/state cookies.
2. Browser is redirected to backend `/oauth/authorize`.
3. Backend creates OAuth session and redirects to frontend `/oauth?session=...`.
4. Frontend login/consent UI calls backend session endpoints (`/oauth/session/*`).
5. Backend returns redirect URL with authorization code.
6. Frontend callback exchanges code at backend `/oauth/token`.
7. Frontend stores access/refresh tokens in cookies and calls protected APIs.
8. On 401, frontend attempts refresh token flow.
## Backend API surface
Key groups from router:
- OAuth routes (`/oauth`)
- `GET /authorize`
- `GET /session/:token`
- `POST /session/login`
- `POST /session/attach`
- `POST /session/approve`
- `POST /token`
- `POST /revoke`
- `POST /introspect`
- User routes (`/api/v1`)
- `POST /auth/register`
- `POST /auth/refresh`
- `GET /me`
- `PATCH /me`
- `DELETE /me`
- `GET /me/consents`
- `DELETE /me/consent/:clientId`
- `GET /me/positions`
- Admin routes (`/api/v1/admin`)
- CRUD for permissions
- CRUD for positions
- assign/revoke positions to users
Security notes:
- protected routes require Bearer access token,
- scopes are checked in middleware,
- admin group additionally requires admin middleware,
- register/login are rate-limited.
## Required environment variables
### Backend
- `SERVER_ADDR` (default `:8080`)
- `FRONTEND_URL` (required)
- `POSTGRES_URL` (required)
- `POSTGRES_MIGRATION_FILE_PATH` (required)
- `REDIS_URL` (required)
- `JWT_SECRET` (required)
- `JWT_TTL` (default `24h`)
- `CLIENT_ID` (required)
- `CLIENT_SECRET` (required)
- `CLIENT_NAME` (optional, default `Basic Client`)
- `CLIENT_REDIRECT_URIS` (comma-separated)
- optional: `CLIENT_GRANT_TYPES`, `CLIENT_SCOPES`
### Frontend
- `PUBLIC_URL` (used for callback URI generation)
- `KOTOSOFT_ID_API_URL` (backend base URL)
- `CLIENT_ID`
- `CLIENT_SECRET`
## How to run locally (development)
Prerequisites:
- Go `1.25.x`
- Node `20+`
- PostgreSQL
- Redis
### Backend
1. `cd kotosoft-id-backend`
2. Set required env vars (or create `.env`)
3. Run:
- `go mod tidy`
- `go run ./cmd`
On startup backend:
- connects to Postgres/Redis,
- runs SQL migrations from `migrations/migrations.sql`,
- seeds/upserts OAuth client from env vars.
### Frontend
1. `cd kotosoft-id-frontend`
2. Install deps: `npm install`
3. Set env vars (`PUBLIC_URL`, `KOTOSOFT_ID_API_URL`, `CLIENT_ID`, `CLIENT_SECRET`)
4. Run dev server: `npm run dev`
## How to run in containers
The provided `docker-compose.yml` expects prebuilt images:
- `localhost:5000/kotosoft_id_backend:latest`
- `localhost:5000/kotosoft_id_frontend:latest`
Typical deployment flow is in `.drone.yml`:
- test backend,
- lint frontend,
- build and push both images,
- deploy with `docker compose up -d`.
## Is it functional?
Short answer: **yes, likely functional as a working auth system**, with normal production caveats.
Why this is likely:
- backend has organized routing/handlers/services/repositories,
- OAuth code flow + refresh + revoke + introspect are implemented,
- user profile and consent endpoints are implemented,
- admin permission/position features are implemented,
- CI runs `go test ./...` for backend and `npm run lint` for frontend.
Caveats:
- no explicit end-to-end test workflow is defined in CI,
- local functionality still depends on correct Postgres/Redis/env configuration,
- deployment compose relies on external image registry and external `proxy` network.
## Important operational notes for AI agents
- Do not assume public API docs exist; use backend router/handlers as source of truth.
- Frontend auth relies on server-side environment variables and secure cookie handling.
- Many failures are configuration failures (wrong redirect URI, client secret, DB/Redis URLs).
- If debugging auth, verify in this order:
1. env vars, 2) OAuth session lifecycle, 3) callback exchange, 4) cookie presence, 5) token refresh.
- For permission issues, check both access token scopes and user admin flag.
## Suggested next docs to add
If you want this project to be easier for both humans and AIs, add:
- a root `README.md` with quick-start commands,
- an `.env.example` for backend and frontend,
- a simple API reference table with request/response examples,
- an end-to-end "happy path" auth walkthrough.