From e85fbf3299312c488ed9b8899d7eb4176170e92b Mon Sep 17 00:00:00 2001 From: Tom Moor Date: Thu, 27 Nov 2025 18:46:38 +0100 Subject: [PATCH] Add AGENTS.md (#10739) --- AGENTS.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..ea7da0f182 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,192 @@ +Outline is a fast, collaborative knowledge base built for teams. It's built with React and TypeScript in both frontend and backend, uses a real-time collaboration engine, and is designed for excellent performance and user experience. The backend is a Koa server with an RPC API and uses PostgreSQL and Redis. The application can be self-hosted or used as a cloud service. + +There is a web client which is fully responsive and works on mobile devices. + +**Monorepo Structure:** + +- **`app/`** - React web application with MobX state management +- **`server/`** - Koa API server with Sequelize ORM and background workers +- **`shared/`** - Shared TypeScript types, utilities, and editor components +- **`plugins/`** - Plugin system for extending functionality +- **`public/`** - Static assets served directly +- **Various config files** - TypeScript, Vite, Jest, Prettier, Oxlint configurations + +Refer to /docs/ARCHITECTURE.md for detailed architecture documentation. + +## Instructions + +You're an expert in the following areas: + +- TypeScript +- React and React Router +- MobX and MobX-React +- Node.js and Koa +- Sequelize ORM +- PostgreSQL +- Redis +- HTML, CSS and Styled Components +- Prosemirror (rich text editor) +- WebSockets and real-time collaboration + +## General Guidelines + +- Use early returns for readability. +- Emphasize type safety and static analysis. +- Follow consistent Prettier formatting. +- Do not replace smart quotes ("") or ('') with simple quotes (""). + +## Dependencies and Upgrading + +- Use yarn for all dependency management. +- After updating dependency versions, install to update lockfiles: + +```bash +yarn install +``` + +## TypeScript Usage + +- Use strict mode. +- Avoid "unknown" unless absolutely necessary. +- Never use "any". +- Prefer type definitions; avoid type assertions (as, !). +- Always use curly braces for if statements. +- Avoid # for private properties. +- Prefer interface over type for object shapes. + +## Classes & Code Organization + +### Class Member Order + +1. Public static variables +2. Public static methods +3. Public variables +4. Public methods +6. Protected variables & methods +8. Private variables & methods + +### Exports + +- Exported members must appear at the top of the file. +- Prefer named exports for components & classes. +- Document ALL public/exported functions with JSDoc. + +## React Usage + +- Use functional components with hooks. +- Event handlers should be prefixed with "handle", like "handleClick" for onClick. +- Avoid unnecessary re-renders by using React.memo, useMemo, and useCallback appropriately. +- Use descriptive prop types with TypeScript interfaces. +- You do not need to import React unless it is used directly. +- Use styled-components for component styling. +- Ensure high accessibility (a11y) standards using ARIA roles and semantic HTML. + +## MobX State Management + +- Use MobX stores for global state management. +- Keep stores in `app/stores/`. +- Use `observable`, `action`, and `computed` decorators appropriately. +- Prefer computed values over manual calculations in render. +- Keep business logic in stores, not components. + +## Database & ORM + +- Use Sequelize models in `server/models/`. +- Generate migrations with Sequelize CLI: + +```bash +yarn sequelize migration:create --name=add-field-to-table +``` + +- Run migrations with `yarn db:migrate`. +- Use transactions for multi-table operations. +- Add appropriate indexes for query performance. +- Always handle database errors gracefully. + +## API Design + +- RESTful endpoints under `/api/`. +- Authentication endpoints under `/auth/`. +- Use consistent error responses. +- Validate request data using the validation middleware and schemas +- Use presenters to format API responses. +- Keep API routes thin, use model methods for business logic, or commands if logic spans multiple models. + +## Authentication & Authorization + +- JWT tokens for authentication. +- Policies in `server/policies/` for authorization. +- Use cancan-style ability checks. +- Use authenticated middleware for protected routes. +- Always verify user permissions before data access. + +## Real-time Collaboration + +- WebSocket connections for real-time updates. +- Use Y.js for collaborative editing. +- Handle connection state changes gracefully. + +## Documentation + +- All public/exported functions & classes must have JSDoc. +- Include: + - Description + - @param and @return (start lowercase, end with period) + - @throws if applicable +- Add a newline between the description and the @ block. +- Use correct punctuation. + +## Testing + +- Run tests with Jest: + +```bash +# Run all tests +yarn test + +# Run specific test suites +yarn test:app # Frontend tests +yarn test:server # Backend tests +yarn test:shared # Shared code tests + +# Run specific test file +yarn test path/to/test.spec.ts +``` + +- Write unit tests for utilities and business logic in a collocated .test.ts file. +- Mock external dependencies appropriately in __mocks__ folder. +- Aim for high code coverage but focus on critical paths. + +## Code Quality + +- Use Oxlint for linting: `yarn lint` +- Format code with Prettier: `yarn format` +- Check types with TypeScript: `yarn tsc` +- Pre-commit hooks run automatically via Husky. +- Fix linting issues before committing. + +## Error Handling + +- Use custom error classes in `server/errors.ts`. +- Always catch and handle errors appropriately. +- Log errors with appropriate context. +- Return user-friendly error messages. +- Never expose sensitive information in errors. + +## Performance + +- Use React.memo for expensive components. +- Implement pagination for large lists. +- Use database indexes effectively. +- Cache expensive computations. +- Monitor performance with appropriate tools. +- Lazy load routes and components where appropriate. + +## Security + +- Sanitize all user input. +- Use CSRF protection. +- Use rateLimiter middleware for sensitive endpoints. +- Follow OWASP guidelines. +- Never store sensitive data in plain text. +- Use environment variables for secrets.