From 1046929e2c2cde3303cbb93c35773b2d2dfc4367 Mon Sep 17 00:00:00 2001 From: Ivan Rezchikov Date: Sat, 11 Jul 2026 20:02:33 +0300 Subject: [PATCH] fix: frontend port exposition --- AI_SYSTEM_DOCS.md | 176 -------------------------------- CODE_STYLE_PROFILE.md | 79 -------------- kotosoft-id-frontend/dockerfile | 2 +- 3 files changed, 1 insertion(+), 256 deletions(-) delete mode 100644 AI_SYSTEM_DOCS.md delete mode 100644 CODE_STYLE_PROFILE.md diff --git a/AI_SYSTEM_DOCS.md b/AI_SYSTEM_DOCS.md deleted file mode 100644 index d8d27b9..0000000 --- a/AI_SYSTEM_DOCS.md +++ /dev/null @@ -1,176 +0,0 @@ -# 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. - diff --git a/CODE_STYLE_PROFILE.md b/CODE_STYLE_PROFILE.md deleted file mode 100644 index b943133..0000000 --- a/CODE_STYLE_PROFILE.md +++ /dev/null @@ -1,79 +0,0 @@ -# Code Style Profile (Go + JSX/Next.js) - -This document captures your current coding style as seen in the repository and lists questions to refine your preferred style rules. - -## Go Style (Observed) - -### What is consistent -- Clear layered architecture: `handlers -> services -> repositories`. -- Short, readable functions with early returns over deep nesting. -- Explicit request/response DTO structs in handlers with Gin binding tags. -- Business logic mostly lives in `services`, SQL mostly in `repositories`. -- Error mapping style is pragmatic (`models.ErrBadRequest`, `ErrForbidden`, etc.). -- Naming is mostly clear and domain-driven (`AssignPosition`, `RecordUserConsent`, `GetUserPositions`). - -### Style characteristics -- You prefer practical over abstract code (few interfaces beyond service boundaries). -- You accept some inline structs for one-off request payloads. -- You keep SQL as raw strings in repository methods (not hidden behind ORM abstractions). -- You usually avoid over-commenting; code is expected to be self-explanatory. -- You follow `gofmt` defaults and avoid stylistic tricks. - -## JSX / Next.js Style (Observed) - -### What is consistent -- Functional components with hooks (`useState`, `useForm`, `useTranslations`). -- Strong TypeScript typing for props and form data. -- UI composition via reusable primitives (`Dialog`, `Table`, `Button`, custom fields). -- Local optimistic state updates after server actions. -- Short handlers with readable names (`handleCreated`, `handleUpdated`, `handleDelete`). -- Frequent early exits on failure (`if (!result.success) { ... return }`). - -### Style characteristics -- You favor compact code and inlined JSX in places where intent is obvious. -- You rely on server actions for API calls and keep transport details in `actions/*`. -- You use translation keys heavily (good i18n discipline). -- You keep component files focused on one domain workflow. - -## Your Answers (Captured) - -### Go -- Error philosophy: undecided for now. -- Strict types over `any`: undecided for now. -- Authorization model: should be based on explicit permissions; admin role is a temporary service mechanism. -- Zero affected rows on update/delete: return `not_found` by default. -- SQL approach: keep inline raw SQL in this project. - -### JSX / Next.js -- Component formatting: compact by default; multiline only when complexity justifies it. -- Mutation strategy today: optimistic updates currently used. -- Validation style: prefer schema-based validation over ad-hoc inline checks. - -## Pending Clarifications - -1. **Optimistic vs refetch default (Q7):** - Recommendation: keep optimistic update as default for snappy UX, and use refetch for high-risk operations (complex server-side side effects, computed fields, permission-dependent payloads). - -2. **Display naming policy (Q8, clarified):** - Proposed rule: in UI, show user-facing label first (`name` or `description`) and fallback to `code` only when label is empty. - Please confirm if you want this as a global rule. - -## Final Summary (Current) - -### Confirmed style rules -- Go authorization should move toward explicit permissions, not role-only checks. -- Go repositories should return `not_found` for update/delete when `0 rows affected`. -- Go SQL stays inline/raw in this project. -- JSX/Next components should be compact by default; multiline formatting is allowed when readability needs it. -- Frontend validation direction is schema-first. - -### Recommended defaults -- Mutation UX: optimistic updates by default; refetch only for risky mutations with possible server-side divergence. -- Action results: migrate from bare `{ success }` to richer result objects: - - success path: `{ success: true, data?: T }` - - error path: `{ success: false, errorCode: string, message?: string }` - -### Still open -- Go error-wrapping strictness (`fmt.Errorf("...: %w", err)` everywhere vs selective). -- Strict ban of `any` in all service/repository boundaries. -- Global UI naming fallback rule (`name/description` first, `code` as fallback). diff --git a/kotosoft-id-frontend/dockerfile b/kotosoft-id-frontend/dockerfile index d1adb4a..cb64ea5 100644 --- a/kotosoft-id-frontend/dockerfile +++ b/kotosoft-id-frontend/dockerfile @@ -14,6 +14,6 @@ COPY --from=builder /app/public ./public COPY --from=builder /app/messages ./messages RUN npm prune --omit=dev EXPOSE 80 -CMD ["npm", "start", "--", "-p", "80", "-H", "0.0.0.0"] +CMD ["npm", "start", "--", "-p", "3000", "-H", "0.0.0.0"] HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ CMD wget -q --spider http://localhost:80/ || exit 1 \ No newline at end of file