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

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)

  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.