Skip to content

armgit / fider

Public Imported from GitHub
0

Open platform to collect and prioritize feedback

Simplified claude.md file

Matt Robertsbe482ccdcd13
diff --git a/CLAUDE.md b/CLAUDE.md
index 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