fix: frontend port exposition
This commit is contained in:
@@ -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.
|
|
||||||
|
|
||||||
@@ -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).
|
|
||||||
@@ -14,6 +14,6 @@ COPY --from=builder /app/public ./public
|
|||||||
COPY --from=builder /app/messages ./messages
|
COPY --from=builder /app/messages ./messages
|
||||||
RUN npm prune --omit=dev
|
RUN npm prune --omit=dev
|
||||||
EXPOSE 80
|
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 \
|
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||||||
CMD wget -q --spider http://localhost:80/ || exit 1
|
CMD wget -q --spider http://localhost:80/ || exit 1
|
||||||
Reference in New Issue
Block a user