Open platform to collect and prioritize feedback
Simplified claude.md file
Matt Robertsbe482ccdcd13
diff --git a/CLAUDE.md b/CLAUDE.mdindex 95fd4739f..5585e8e41 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,215 +1,376 @@# CLAUDE.md-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.+This file provides guidance to Claude Code when working with the Fider codebase.-## Common Development Commands+## Repository Structure-### Building+**Backend (Go):**-- `make build` - Build both server and UI-- `make build-server` - Build Go server binary-- `make build-ui` - Build UI assets with webpack-- `make build-ssr` - Build SSR script and compile locales+- `app/handlers/` - HTTP request handlers+- `app/models/` - Data models (entity, cmd, query, action, dto)+- `app/services/` - Business logic and external service integrations+- `app/pkg/bus/` - Service registry and dispatch system+- `app/cmd/routes.go` - All HTTP routes defined here+- `migrations/` - Database migrations (numbered SQL files)-### Running+**Frontend (React/TypeScript):**-- `make run` - Run Fider server (requires build first)-- `make watch` - Start both server and UI in watch mode (recommended for development)-- `make watch-server` - Run server in watch mode with air-- `make watch-ui` - Run UI in watch mode with webpack-- `make migrate` - Run database migrations--### Testing--- `make test` - Run both server and UI tests-- `make test-server` - Run Go server tests (includes migration)-- `make test-ui` - Run Jest tests for React components-- `make coverage-server` - Run server tests with coverage-- `make test-e2e-server` - Run E2E tests for server features-- `make test-e2e-ui` - Run E2E tests for UI features--### Linting--- `make lint` - Lint both server and UI code-- `make lint-server` - Run golangci-lint on Go code-- `make lint-ui` - Run ESLint on TypeScript/React code--### Other--- `make clean` - Remove build artifacts-- `make help` - Show all available make targets--## Project Architecture+- `public/pages/` - Page components (lazy-loaded)+- `public/components/` - Reusable UI components+- `public/services/` - Client-side services and API calls+- `public/hooks/` - Custom React hooks+- `public/assets/styles/` - SCSS styles with utility classes-### Backend (Go)+**Configuration:**-Fider uses a layered architecture with clean separation of concerns:+- `.env` - Local environment config (copy from `.example.env`)+- `Makefile` - Build and development commands-**Core Structure:**+## Local Development-- `main.go` - Entry point with command routing (ping, migrate, server)-- `app/cmd/` - Command implementations and server bootstrap-- `app/cmd/routes.go` - All routes are defined here-- `app/handlers/` - HTTP handlers organized by functionality-- `app/middlewares/` - HTTP middleware chain-- `app/models/` - Data models (cmd, dto, entity, enum, query)-- `app/services/` - Service implementations with dependency injection-- `app/pkg/` - Reusable packages and utilities+All commands are defined in the Makefile.-**Key Patterns:**+**Development:**-- **Bus Architecture**: Uses `app/pkg/bus` for service registration and dispatch-- **CQRS**: Commands and queries are separated in `app/models/`-- **Service Layer**: All external services (email, blob storage, oauth) are abstracted-- **Middleware Chain**: Authentication, tenant resolution, CORS, etc.+- `make watch` - Hot reload for both server and UI (use this for active development)+- `make migrate` - Run database migrations-**Database:**+**Testing:**-- PostgreSQL with custom migration system in `migrations/`-- SQL-based data access through service interfaces-- Tenant-aware data isolation+- `make test` - Run all tests (both Go and Jest)+- `make lint` - Lint both server and UI code-### Frontend (React/TypeScript)+Essential: Run "make lint" and "make test" when you've completed any changes, to check the formatting and tests.-Modern React application with TypeScript:+**Building:**-**Structure:**+- `make build` - Build production-ready binaries and assets-- `public/index.tsx` - Application entry point with React 18-- `public/components/` - Reusable UI components-- `public/pages/` - Page-level components organized by feature-- `public/services/` - Client-side services and utilities-- `public/hooks/` - Custom React hooks+## Code Patterns & Examples-**Key Features:**+### Backend: Adding a New API Endpoint-- **SSR Support**: Server-side rendering with hydration-- **Internationalization**: LinguiJS for i18n with locale switching-- **Component Library**: Extensive set of reusable components-- **State Management**: React Context for global state-- **Error Boundaries**: Comprehensive error handling+**1. Define the route** in `app/cmd/routes.go`:-**Build System:**+```go+// Public API+engine.Get("/api/v1/posts", handlers.SearchPosts())-- Webpack for bundling with CSS extraction-- ESBuild for SSR compilation-- SCSS for styling with utility classes-- Asset optimization and code splitting+// Authenticated API (requires login)+engine.Get("/api/v1/user/settings", middlewares.IsAuthenticated(), handlers.UserSettings())-### API Design+// Admin only+engine.Post("/api/v1/admin/members", middlewares.IsAuthenticated(), middlewares.IsAuthorized(enum.RoleAdministrator), handlers.CreateMember())+```-RESTful API with multiple access levels:+**2. Create the handler** in `app/handlers/`:-- `/api/v1/` - Public API (no auth required)-- Member API - Authenticated users-- Staff API - Collaborators and administrators-- Admin API - Administrators only+```go+package handlers-### Key Services+import (+ "github.com/getfider/fider/app/models/cmd"+ "github.com/getfider/fider/app/models/query"+ "github.com/getfider/fider/app/pkg/bus"+ "github.com/getfider/fider/app/pkg/web"+)-The application includes pluggable services for:+// SearchPosts returns posts matching criteria+func SearchPosts() web.HandlerFunc {+ return func(c *web.Context) error {+ q := &query.SearchPosts{+ Query: c.QueryParam("query"),+ Limit: 10,+ }-- **Email**: SMTP, Mailgun, AWS SES-- **Blob Storage**: Filesystem, S3, SQL-- **OAuth**: Custom providers, GitHub, Google, etc.-- **Billing**: Paddle integration (optional)-- **Webhooks**: Outbound event notifications+ if err := bus.Dispatch(c, q); err != nil {+ return c.Failure(err)+ }-## Development Setup Requirements+ return c.Ok(q.Result)+ }+}+```-1. **Go 1.22+** - Backend development-2. **Node.js 21/22** - Frontend build tools and TypeScript-3. **Docker** - PostgreSQL and local SMTP (MailHog)-4. **Air** - Go hot reload: `go install github.com/cosmtrek/air`-5. **Godotenv** - Environment loading: `go install github.com/joho/godotenv/cmd/godotenv`-6. **golangci-lint** - Go linting: `go install github.com/golangci/golangci-lint/v2/cmd/[email protected]`+**3. Define the query** in `app/models/query/`:-**Environment Setup:**+```go+package query++import "github.com/getfider/fider/app/models/entity"++type SearchPosts struct {+ Query string+ Limit int+ Result []*entity.Post+}+```++**4. Implement the service** in `app/services/`:++```go+package postgres++import (+ "github.com/getfider/fider/app/models/query"+ "github.com/getfider/fider/app/pkg/dbx"+)++func searchPosts(ctx context.Context, q *query.SearchPosts) error {+ return using(ctx, func(trx *dbx.Trx, tenant *entity.Tenant, user *entity.User) error {+ q.Result = []*entity.Post{}+ return trx.Select(&q.Result,+ "SELECT * FROM posts WHERE title ILIKE $1 LIMIT $2",+ "%"+q.Query+"%", q.Limit,+ )+ })+}++func init() {+ bus.Register(Service{})+}++func (s Service) Name() string {+ return "Postgres"+}++func (s Service) Category() string {+ return "sqlstore"+}++func (s Service) Enabled() bool {+ return true+}++func (s Service) Init() {+ bus.AddHandler(searchPosts)+}+```++### Frontend: Calling the API from React++```typescript+// In a React component+import { http } from "@fider/services"++export const PostSearch: React.FC = () => {+ const [posts, setPosts] = React.useState([])+ const [query, setQuery] = React.useState("")++ const handleSearch = async () => {+ const result = await http.get<Post[]>(`/api/v1/posts?query=${query}`)+ if (result.ok) {+ setPosts(result.data)+ }+ }++ return (+ <div className="c-post-search">+ <input className="c-post-search__input" value={query} onChange={(e) => setQuery(e.target.value)} />+ <Button onClick={handleSearch}>Search</Button>+ </div>+ )+}+```++### Model Naming Conventions++Use these strict prefixes in `app/models/`:++```go+// entity.* - Database tables+type entity.User struct {+ ID int+ Name string+ Email string+}++// action.* - User input for POST/PUT/PATCH (maps 1:1 to commands)+type action.CreatePost struct {+ Title string+ Description string+}++// cmd.* - Commands to execute (potentially return values)+type cmd.SendEmail struct {+ To string+ Subject string+ Body string+}++// query.* - Queries to fetch data+type query.GetPostByID struct {+ PostID int+ Result *entity.Post+}++// dto.* - Data transfer between packages+type dto.PostInfo struct {+ Title string+ AuthorName string+}+```++### CSS Conventions++Most pages have a corresponding scss file. For example Home.Page.tsx imports Home.Page.scss which contains styles for various components in that page. These follow a BEM style:++```scss+// Page ID: p-<page_name>+#p-home {+ // Component: c-<component>+ .c-post-list {+ // Element: c-<component>__<element>+ &__item {+ padding: 1rem;+ }++ &__title {+ font-size: 1.2rem;+ }++ // Modifier: c-<component>--<state>+ &--loading {+ opacity: 0.5;+ }+ }+}+```++However, more recently, Utility classes were added to the codebase, to make it possible to apply classes in a utility style, similar to tailwind. If possible favour the utility classes over adding new styles for components and pages:++```scss+// Utility classes (no prefix) - defined in public/assets/styles/utility/+.mt-2 {+ margin-top: 0.5rem;+}+.flex {+ display: flex;+}+```++Important: Do not just apply tailwind classes to new code, tailwind is not in use in this project. Check what is available in the utility scss files.++## Common Tasks++### Creating a Database Migration++"up migrations" only.++```bash+# Create new migration file in migrations/ directory+# Format: YYYYMMDDHHMMSS_description.sql+# Example: migrations/202601041200_add_user_preferences.sql++CREATE TABLE user_preferences (+ id SERIAL PRIMARY KEY,+ user_id INTEGER NOT NULL REFERENCES users(id),+ theme VARCHAR(50),+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()+);-- Copy `.example.env` to `.env` for local configuration-- Run `docker compose up -d` for PostgreSQL and MailHog-- MailHog UI available at http://localhost:8025+```-## Testing Strategy+Run with: `make migrate`-**Backend Testing:**+### Adding a New Page Component++```typescript+// public/pages/MyNewPage/MyNewPage.page.tsx+import React from "react"+import { Page } from "@fider/components"++interface MyNewPageProps {+ // Props here+}-- Unit tests alongside source files (`*_test.go`)-- Integration tests with test database-- E2E tests using Cucumber for server features+const MyNewPage: React.FC<MyNewPageProps> = (props) => {+ return (+ <Page id="p-my-new-page">+ <h1>My New Page</h1>+ </Page>+ )+}-**Frontend Testing:**+export default MyNewPage+```-- Jest for unit/component tests-- Testing Library for React components-- E2E tests using Cucumber + Playwright+```typescript+// public/pages/MyNewPage/index.ts+export { default as MyNewPage } from "./MyNewPage.page"+```-**Test Environment:**+Register route in `app/handlers/` and lazy-load in `public/index.tsx`.-- Uses `.test.env` for test-specific configuration-- Automated database migrations before test runs-- Coverage reporting available+### Using the Bus System-## Code Organization Principles+The bus handles service registration and dispatch:-### Backend Model Naming Conventions+```go+// Register a service+bus.Register(MyService{})-Follow these strict naming patterns for `app/models/`:+// Dispatch a query+q := &query.GetUserByID{UserID: 123}+if err := bus.Dispatch(ctx, q); err != nil {+ return err+}+user := q.Result-- **`action.<something>`** - User interactions for POST/PUT/PATCH requests, map 1-to-1 with Commands (e.g., `action.CreateNewUser`)-- **`dto.<something>`** - Data transfer objects between packages/services (e.g., `dto.NewUserInfo`)-- **`entity.<something>`** - Objects mapped to database tables (e.g., `entity.User`)-- **`cmd.<something>`** - Commands that must be executed and potentially return values (e.g., `cmd.HttpRequest`, `cmd.LogDebug`, `cmd.SendMail`, `cmd.CreateNewUser`)-- **`query.<something>`** - Queries to get information from somewhere (e.g., `query.GetUserById`, `query.GetAllPosts`)+// Dispatch a command+c := &cmd.SendEmail{To: "[email protected]", Subject: "Welcome"}+if err := bus.Dispatch(ctx, c); err != nil {+ return err+}+```-### Frontend Structure Conventions+## Architecture Patterns-- **Page Organization**: Each page has its own folder under `public/pages/` with:- - `index.ts` - Module exporter- - `[PageName].page.tsx` - Main page component- - `[PageName].page.scss` - Page-specific styles- - `[PageName].page.spec.tsx` - Unit tests- - `./components/` - Page-specific components+**Backend (Go):**-### CSS Naming Conventions+- CQRS: Separate commands (write) and queries (read)+- Bus system: Dependency injection and service dispatch+- Middleware chain: Auth, tenant resolution, CORS applied via routes+- SQL-based data access: Direct SQL queries, no ORM-Fider uses BEM methodology combined with utility classes:+**Frontend (React):**-- **`p-<page_name>`** - HTML ID for each page component (e.g., `p-home`, `p-user-settings`)-- **`c-<component_name>`** - Block class for components (e.g., `c-toggle`)-- **`c-<component_name>__<element>`** - Element classes (e.g., `c-toggle__label`)-- **`c-<component_name>--<state>`** - State modifiers (e.g., `c-toggle--checked`)-- **`is-<state>`, `has-<state>`** - Global state modifiers-- **Utility classes** - No prefix, used for common styling patterns. All utility classes are defined in public/assets/styles/utility/+- SSR Support: Server-side rendering with React 18 hydration+- i18n: LinguiJS for translations+- Code splitting: Lazy-loaded page components+- Type safety: Full TypeScript coverage-### General Principles+## Troubleshooting-**Backend:**+**Database connection errors:**-- Services are dependency-injected through the bus system-- All external dependencies are abstracted behind interfaces-- Database queries are centralized in query objects-- Handlers focus on HTTP concerns, business logic in services+- Ensure Docker is running: `docker compose ps`+- Check `.env` has correct `DATABASE_URL`+- Run migrations: `make migrate`-**Frontend:**+**Build failures:**-- Page components are lazy-loaded for performance-- Shared components in `components/common/`-- Business logic in services, not components-- Type-safe API calls with proper error handling+- Clear build cache: `make clean && make build`+- Check Go version: `go version` (need 1.22+)+- Check Node version: `node --version` (need 21/22)-## Build and Deployment+**Tests failing:**-**Local Development:**+- Ensure test database is migrated (happens automatically with `make test`)+- Check `.test.env` configuration+- Run specific test: `go test ./app/handlers -v -run TestName`-- `make watch` for development with hot reload-- Webpack dev server for fast UI rebuilds-- Air for Go server hot reload+**Port conflicts:**-**Production Build:**+- Default ports: 3000 (app), 5432 (postgres), 8025 (mailhog)+- Change in `.env` if needed-- `make build` creates optimized binaries and assets-- SSR compilation for better SEO and performance-- Asset optimization and minification+## Development Tips-This is a mature, production-ready feedback platform with comprehensive testing, i18n support, and a clean, maintainable architecture.+- Use `make watch` for active development - it handles hot reload for both frontend and backend+- MailHog captures all emails at http://localhost:8025+- Frontend changes: Webpack rebuilds automatically+- Backend changes: Air restarts server automatically+- All routes are centralized in `app/cmd/routes.go` - start there when tracing request flow+- Bus handlers are registered in service `Init()` methods+- Utility CSS classes are in `public/assets/styles/utility/` - use these before adding custom styles