From 3813a3b35ce3254cdd60fc659b488fa35690ed7b Mon Sep 17 00:00:00 2001 From: kolaente Date: Tue, 10 Jun 2025 13:14:26 +0200 Subject: [PATCH] docs: add AGENTS.md file with instructions for AI coding agents --- AGENTS.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 201 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..8118e0c2a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,200 @@ +# AGENT Instructions + +## Project Overview + +Vikunja is a comprehensive todo and task management application with a Vue.js frontend and Go backend. It supports multiple project views (List, Kanban, Gantt, Table), team collaboration, file attachments, and extensive integrations. + +The project consists of: +- `pkg/` – Go code for the API service +- `frontend/` – Vue.js based web client +- `magefile.go` – Mage build script providing tasks for development and release +- `desktop/` – Electron wrapper application +- `docs/` – Documentation website + +## Development Commands + +### Backend (Go) +- **Build**: `mage build` - Builds the Go binary +- **Test**: `mage test:unit` - Runs unit tests +- **Test Integration**: `mage test:integration` - Runs integration tests +- **Test All**: `mage test:all` - Runs all tests +- **Lint**: `mage lint` - Runs golangci-lint +- **Lint Fix**: `mage lint:fix` - Runs golangci-lint with auto-fix +- **Generate Swagger Docs**: `mage generate:swagger-docs` - Updates API documentation (Generally you won't need to run this unless the user tells you to. It is updated automatically in the CI workflow) +- **Check Swagger**: `mage check:got-swag` - Verifies swagger docs are up to date +- **Generate Config**: `mage generate:config-yaml` - Generate sample config from `config-raw.json` +- **Clean**: `mage build:clean` - Cleans build artifacts +- **Format**: `mage fmt` - Format Go code before committing + +Development helpers under the `dev` namespace: +- **Migration**: `mage dev:make-migration` - Creates new database migration +- **Event**: `mage dev:make-event` - Create an event type +- **Listener**: `mage dev:make-listener` - Create an event listener +- **Notification**: `mage dev:make-notification` - Create a notification skeleton + +### Frontend (Vue.js) +Navigate to `frontend/` directory: +- **Dev Server**: `pnpm dev` - Starts development server +- **Build**: `pnpm build` - Production build +- **Build Dev**: `pnpm build:dev` - Development build +- **Lint**: `pnpm lint` - ESLint check +- **Lint Fix**: `pnpm lint:fix` - ESLint with auto-fix +- **Type Check**: `pnpm typecheck` - Vue TypeScript checking +- **Test Unit**: `pnpm test:unit` - Vitest unit tests +- **Test E2E**: `pnpm test:e2e` - Cypress end-to-end tests +- **Test E2E Dev**: `pnpm test:e2e-dev` - Interactive Cypress testing + +### Pre-commit Checks +Always run both lint before committing: +```bash +# Backend +mage lint:fix + +# Frontend +cd frontend && pnpm lint:fix +``` + +Fix any errors the lint commands report, then try comitting again. + +You only need to run the lint for the backend when changing backend code, and the lint for the frontend only when changing frontend code. + +## Architecture Overview + +### Backend Architecture (Go) +The Go backend follows a layered architecture with clear separation of concerns: + +**Core Layers:** +- **Models** (`pkg/models/`) - Domain entities with business logic and CRUD operations +- **Services** (`pkg/services/`) - Business logic layer handling complex operations +- **Routes** (`pkg/routes/`) - HTTP API endpoints and routing configuration +- **Web** (`pkg/web/`) - Generic CRUD handlers and web framework abstractions + +**Key Patterns:** +- **Generic CRUD**: Models implement `CRUDable` interface for standardized database operations +- **Rights System**: Three-tier permissions (Read/Write/Admin) enforced across all operations +- **Event-Driven**: Event system for notifications, webhooks, and cross-cutting concerns +- **Modular Design**: Pluggable authentication, avatar providers, migration tools + +**Database:** +- XORM ORM with support for MySQL, PostgreSQL, SQLite +- Migration system in `pkg/migration/` with timestamped files +- Database sessions with automatic transaction handling + +**Authentication:** +- Multi-provider: Local, LDAP, OpenID Connect +- JWT tokens for API access +- API tokens with scoped permissions +- TOTP/2FA support + +### Frontend Architecture (Vue.js) +Modern Vue 3 composition API application with TypeScript: + +**State Management:** +- **Pinia** stores in `src/stores/` for global state +- Composables in `src/composables/` for reusable logic +- Component-level state with Vue 3 Composition API + +**Key Directories:** +- `src/components/` - Reusable Vue components organized by feature +- `src/views/` - Page-level components and routing +- `src/stores/` - Pinia state management +- `src/services/` - API service layer matching backend models +- `src/models/` - TypeScript interfaces matching backend models +- `src/helpers/` - Utility functions and business logic + +**UI Framework:** +- Bulma CSS framework with CSS variables for theming +- FontAwesome icons with tree-shaking +- TipTap rich text editor for task descriptions +- Custom component library in `src/components/base/` + +## Development Workflows + +### Adding New Features + +**Backend Changes:** +1. Create/modify models in `pkg/models/` with proper CRUD and Rights interfaces as required +2. Add database migration if needed: `mage dev:make-migration` +3. Create/update services in `pkg/services/` for complex business logic +4. Add API routes in `pkg/routes/api/v1/` following existing patterns +5. Update Swagger annotations + +**Frontend Changes:** +1. Create TypeScript interfaces in `src/modelTypes/` matching backend models +2. Add/update services in `src/services/` for API communication +3. Create components in appropriate `src/components/` subdirectories +4. Add views/pages in `src/views/` with proper routing +5. Update Pinia stores if global state changes are needed + +### Database Changes +1. Run `mage dev:make-migration` and enter the struct name +2. Edit the generated migration file in `pkg/migration/` +3. Update corresponding model in `pkg/models/` +4. Update TypeScript interfaces in frontend `src/modelTypes/` + +### API Development +- All API endpoints follow RESTful conventions under `/api/v1/` +- Use generic web handlers in `pkg/web/handler/` for standard CRUD operations +- Implement proper rights checking using the Rights interface +- Add Swagger annotations for automatic documentation generation + +### Testing +- Backend: Unit tests alongside source files, integration tests in `pkg/integrations/` +- Frontend: Unit tests with Vitest, E2E tests with Cypress +- Always test both positive and negative authorization scenarios +- Use test fixtures in `pkg/db/fixtures/` for consistent test data + +## Swagger API Documentation + +Never touch the generated swagger api documentation under `pkg/swagger/`. These are automatically generated by CI after committing. + +## Commit Messages + +Use the **Conventional Commits** style when committing changes (for example, `feat: add foo` or `fix: correct bar`). This repository uses these messages to generate changelogs. + +## Frontend Development Guidelines + +The web client lives in `frontend/` and uses Vue.js 3 in combination with TypeScript. + +Check the `frontend/.editorconfig` file and obey the formatting rules outlined there. + +## Translations + +When adding or changing functionality which touches user-facing messages, these need to be translated. + +In the frontend, all translation strings live in `frontend/src/i18n/lang`. For the api (which mainly affects the localization of notifications), the strings live in `pkg/i18n/lang`. + +You only need to adjust the `en.json` file with the source string. The actual translation happens elsewhere. +After adjusting the source string, you need to call the respective translation library with the key. Both are similar, check the existing code to figure it out. + +## Key Files and Conventions + +**Configuration:** +- `config.yml.sample` - Example configuration (generated from `config-raw.json`) +- Environment variables override config file settings +- Use `pkg/config/` for configuration management + +**Code Style:** +- Go: Standard Go formatting with golangci-lint +- Vue: ESLint with TypeScript and Vue-specific rules +- Follow existing patterns for consistency + +**Naming Conventions:** +- Go: Standard Go conventions (PascalCase for exports, camelCase for private) +- Vue: PascalCase for components, camelCase for composables +- API endpoints: kebab-case in URLs, camelCase in JSON + +**Rights and Permissions:** +- Always implement Rights interface for new models +- Use `CanRead`, `CanWrite`, `CanCreate`, `CanDelete` methods +- Rights are enforced at the model level, not just routes + +## Common Gotchas + +- Database migrations are irreversible in production - test thoroughly +- Frontend services must match backend model structure exactly +- Rights checking is mandatory for all CRUD operations +- Event listeners in `pkg/*/listeners.go` must be registered properly +- CORS settings in backend must allow frontend domain +- API tokens have different scopes - check permissions carefully + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file