Conversation
- Expand project overview to include both Device Flow and Authorization Code Flow with PKCE. - Add setup instructions for development, template code generation, and Swagger doc generation. - Update project structure to use internal/ directories and add more detailed descriptions for each layer and model. - Document support for both confidential and public OAuth client types. - Add explicit Technology Stack section, listing frameworks, libraries, and tools used. - Replace environment variable table with categorized configuration guidance and highlight `.env.example` as reference. - List and explain all core endpoints for OAuth, user/device management, authentication, and admin actions. - Include new endpoints for admin actions, OAuth provider login, audit logging, metrics, and Swagger docs. - Emphasize the importance of running `make generate` when modifying templates and before building. - Enhance documentation of recommended use of interfaces for pluggable components, while promoting direct struct injection for others. - Add API documentation instructions using Swagger annotations. - Update contribution checklist: require code generation before tests, formatting, and linting. - Add key details for metrics, caching, rate limiting, and third-party authentication. Signed-off-by: appleboy <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR comprehensively updates the CLAUDE.md documentation file to reflect the expanded OAuth capabilities and provide better guidance for development workflows. The documentation now covers both Device Authorization Grant (RFC 8628) and Authorization Code Flow with PKCE (RFC 6749/7636), along with detailed setup instructions and architectural guidance.
Changes:
- Expanded OAuth flow documentation to include Authorization Code Flow with PKCE alongside Device Flow
- Added comprehensive setup and development workflow instructions (make generate, swagger, dev commands)
- Enhanced project structure documentation with internal/ directories and detailed model descriptions
- Added Technology Stack section listing all frameworks and tools
- Reorganized configuration guidance to reference .env.example and docs/CONFIGURATION.md
- Documented all core API endpoints with categorization (OAuth, User/Device Management, Authentication, Admin, System)
- Updated coding conventions to emphasize template generation requirements and interface design patterns
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - `GET /oauth/:provider` - Initiate OAuth login (GitHub, Gitea, Microsoft) | ||
| - `GET /oauth/:provider/callback` - OAuth callback handler |
There was a problem hiding this comment.
The OAuth provider endpoints are incorrect. According to the actual route configuration in main.go (lines 1028-1030), the routes should be:
GET /auth/login/:provider- Initiate OAuth loginGET /auth/callback/:provider- OAuth callback handler
Not /oauth/:provider and /oauth/:provider/callback as currently documented.
| - `GET /oauth/:provider` - Initiate OAuth login (GitHub, Gitea, Microsoft) | |
| - `GET /oauth/:provider/callback` - OAuth callback handler | |
| - `GET /auth/login/:provider` - Initiate OAuth login (GitHub, Gitea, Microsoft) | |
| - `GET /auth/callback/:provider` - OAuth callback handler |
|
|
||
| - `GET /health` - Health check with database connection test | ||
| - `GET /metrics` - Prometheus metrics (optional Bearer token auth) | ||
| - `GET /api/swagger/*` - Swagger/OpenAPI documentation |
There was a problem hiding this comment.
The Swagger endpoint path is incorrect. According to the route configuration in main.go (line 490), the Swagger documentation is served at /swagger/* not /api/swagger/* as documented.
| - `GET /api/swagger/*` - Swagger/OpenAPI documentation | |
| - `GET /swagger/*` - Swagger/OpenAPI documentation |
| - `GET /admin/clients/new` - Create new OAuth client | ||
| - `POST /admin/clients` - Save new OAuth client | ||
| - `GET /admin/clients/:id/edit` - Edit OAuth client | ||
| - `POST /admin/clients/:id/update` - Update OAuth client |
There was a problem hiding this comment.
The endpoint path for updating OAuth clients is incorrect. According to the route configuration in main.go (line 558), the update endpoint is POST /admin/clients/:id not POST /admin/clients/:id/update as documented.
| - `POST /admin/clients/:id/update` - Update OAuth client | |
| - `POST /admin/clients/:id` - Update OAuth client |
| - Never edit `_templ.go` files directly - always edit the source `.templ` files | ||
| - Run `make generate` after modifying any `.templ` file | ||
| - **Interfaces**: Follow Go best practices - define interfaces where abstraction adds value | ||
| - **Currently have interfaces**: `Cache`, `MetricsCollector` (swappable implementations) |
There was a problem hiding this comment.
The interface name is incorrect. According to internal/metrics/interface.go, the metrics interface is named MetricsRecorder, not MetricsCollector.
| - **Currently have interfaces**: `Cache`, `MetricsCollector` (swappable implementations) | |
| - **Currently have interfaces**: `Cache`, `MetricsRecorder` (swappable implementations) |
.env.exampleas reference.make generatewhen modifying templates and before building.