5.3 KiB
5.3 KiB
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)
- Frontend starts OAuth initiation (
/api/auth/initiate) and creates PKCE verifier/state cookies. - Browser is redirected to backend
/oauth/authorize. - Backend creates OAuth session and redirects to frontend
/oauth?session=.... - Frontend login/consent UI calls backend session endpoints (
/oauth/session/*). - Backend returns redirect URL with authorization code.
- Frontend callback exchanges code at backend
/oauth/token. - Frontend stores access/refresh tokens in cookies and calls protected APIs.
- On 401, frontend attempts refresh token flow.
Backend API surface
Key groups from router:
- OAuth routes (
/oauth)GET /authorizeGET /session/:tokenPOST /session/loginPOST /session/attachPOST /session/approvePOST /tokenPOST /revokePOST /introspect
- User routes (
/api/v1)POST /auth/registerPOST /auth/refreshGET /mePATCH /meDELETE /meGET /me/consentsDELETE /me/consent/:clientIdGET /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(default24h)CLIENT_ID(required)CLIENT_SECRET(required)CLIENT_NAME(optional, defaultBasic 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_IDCLIENT_SECRET
How to run locally (development)
Prerequisites:
- Go
1.25.x - Node
20+ - PostgreSQL
- Redis
Backend
cd kotosoft-id-backend- Set required env vars (or create
.env) - Run:
go mod tidygo run ./cmd
On startup backend:
- connects to Postgres/Redis,
- runs SQL migrations from
migrations/migrations.sql, - seeds/upserts OAuth client from env vars.
Frontend
cd kotosoft-id-frontend- Install deps:
npm install - Set env vars (
PUBLIC_URL,KOTOSOFT_ID_API_URL,CLIENT_ID,CLIENT_SECRET) - Run dev server:
npm run dev
How to run in containers
The provided docker-compose.yml expects prebuilt images:
localhost:5000/kotosoft_id_backend:latestlocalhost: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 andnpm run lintfor 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
proxynetwork.
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:
- 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.mdwith quick-start commands, - an
.env.examplefor backend and frontend, - a simple API reference table with request/response examples,
- an end-to-end "happy path" auth walkthrough.