AGENTS.md

1# AGENTS.md — flagsmith
2 
3## Project Overview
4 
5Flagsmith is an open-source feature flagging and remote configuration management tool. It allows teams to manage feature releases, perform A/B testing, and toggle application functionality without deploying new code. The tech stack is centered around a Python/Django backend API and a TypeScript/React single-page application frontend, designed to be self-hosted with Docker or used as a SaaS product.
6 
7## Tech Stack
8 
9-   **Languages**: Python, TypeScript
10-   **Frameworks**: Django, Django REST Framework, React, Redux Toolkit
11-   **Database**: PostgreSQL
12-   **Dependency Management**: Poetry (Backend), npm (Frontend)
13-   **Testing**: `pytest` (Backend Unit & Integration), Jest (Frontend Unit), TestCafe (Frontend E2E)
14-   **Formatting & Linting**: `black`, `isort` (Backend); Prettier, ESLint (Frontend)
15-   **DevOps & Infrastructure**: Docker, Docker Compose
16-   **Error Monitoring**: Sentry, Prometheus
17 
18## Architecture
19 
20The project uses a monorepo structure, separating the backend, frontend, and documentation into distinct top-level directories. It follows a client-server model with a monolithic Django API and a React Single-Page Application (SPA).
21 
22-   `api/`: The monolithic Django backend.
23    -   `api/features/`, `api/organisations/`, `api/users/`: Modular Django apps, each containing its own models, views, and serializers, promoting separation of concerns.
24    -   `api/tests/`: Contains all backend tests, subdivided into `unit/` and `integration/`.
25    -   `api/pyproject.toml`: Defines all Python dependencies managed by Poetry.
26-   `frontend/`: The React SPA frontend.
27    -   `frontend/web/`: Main source code for the application.
28    -   `frontend/web/components/`: Reusable React components form the core of the UI.
29    -   `frontend/common/`: Contains shared logic, including state management.
30    -   `frontend/common/store.ts`: The central Redux Toolkit store configuration.
31    -   `frontend/common/service.ts`: The single RTK Query service definition that handles all API communication.
32    -   `frontend/e2e/`: End-to-end tests written with TestCafe.
33    -   `frontend/package.json`: Defines all frontend dependencies managed by npm.
34-   `docs/`: Project documentation built with Docusaurus.
35-   `docker-compose.yml`: The entry point for setting up the entire local development environment.
36 
37## Code Style
38 
39The codebase maintains a strict and consistent style through automated formatters and linters.
40 
41**Backend (Python):**
42-   **Formatting**: Code is formatted with `black` and imports are sorted with `isort`. These tools are configured in `api/pyproject.toml` and must be run before committing.
43-   **Naming**: Follows standard Python PEP 8 conventions (e.g., `snake_case` for variables and functions, `PascalCase` for classes).
44-   **Views**: Class-based views are used, inheriting from Django REST Framework's `APIView`. Business logic should not reside in the view itself but be abstracted into model methods or service functions.
45 
46Example of a backend view (`api/audit/views.py`):
47```python
48from rest_framework.response import Response
49from rest_framework.views import APIView
50from audit.models import AuditLog
51 
52class AuditLogCount(APIView):
53    def get(self, request, *args, **kwargs):
54        count = AuditLog.objects.count()
55        return Response({'count': count})
56```
57 
58**Frontend (TypeScript/React):**
59-   **Formatting**: Code is automatically formatted using **Prettier**.
60-   **Linting**: **ESLint** is used to enforce code quality and best practices.
61-   **Components**: Functional components with Hooks are standard.
62-   **Data Fetching**: All data fetching is done via auto-generated RTK Query hooks.
63 
64Example of a frontend component (`frontend/web/components/AuditLogCounter.tsx`):
65```typescript
66import React from 'react';
67import { useGetAuditLogCountQuery } from 'common/service';
68 
69export const AuditLogCounter = () => {
70    const { data, isLoading, error } = useGetAuditLogCountQuery({});
71 
72    if (isLoading) return <div>Loading...</div>;
73    if (error) return <div>Error fetching count!</div>;
74 
75    return <h1>Total Audit Logs: {data?.count}</h1>;
76};
77```
78 
79## Anti-Patterns & Restrictions
80 
81To maintain architectural integrity and code quality, the following rules must be strictly followed:
82 
83-   **Frontend:**
84    -   **NEVER** make direct API calls from components using `fetch` or `axios`. **ALWAYS** use the RTK Query service layer defined in `frontend/common/service.ts`.
85    -   **NEVER** introduce a new global state management library. All global state must be managed via the existing Redux Toolkit store (`frontend/common/store.ts`).
86 
87-   **Backend:**
88    -   **NEVER** bypass the Django ORM for database operations unless it is for a critical, well-documented performance optimization.
89    -   **AVOID** placing complex business logic directly within Django views (`views.py`). This logic should be abstracted into separate service functions or model methods to keep views lean and focused on handling the HTTP request/response cycle.
90 
91## Database & State Management
92 
93The application manages state and data flow differently on the backend and frontend.
94 
95**Backend (Database):**
96-   The primary database is **PostgreSQL**.
97-   All database interactions are handled exclusively through the **Django ORM**. Direct SQL queries are forbidden except in rare, documented cases.
98-   Database schemas are defined as Django models within each app's `models.py` file (e.g., `api/features/models.py`).
99-   Schema changes must be managed through Django's migration system. New migrations are created with `poetry run python manage.py makemigrations` and applied with `poetry run python manage.py migrate`.
100 
101**Frontend (State):**
102-   **Server State & Caching**: All interactions with the backend API (fetching, creating, updating, deleting data) are managed by **RTK Query**. The API service definition is located in `frontend/common/service.ts`. This provides hooks that handle the entire data lifecycle, including caching, invalidation, and optimistic updates.
103-   **Global UI State**: Global state that is not persisted on the server (e.g., modal visibility, UI themes) is managed by **Redux Toolkit**. The store is configured in `frontend/common/store.ts`. New state is added by creating a new "slice" with `createSlice`.
104 
105## Error Handling & Logging
106 
107-   **Backend**:
108    -   **Logging**: Uses Python's standard `logging` module, configured in `api/app/settings/common.py`. Logs should be used to record important events and debug issues.
109    -   **Error Reporting**: In production, unhandled exceptions are captured and reported to **Sentry**. The Sentry integration is configured via environment variables.
110 
111-   **Frontend**:
112    -   **Error Reporting**: Unhandled client-side exceptions are captured and sent to **Sentry**.
113    -   **Error Boundaries**: Components that have a high chance of failing or depend on fragile data should be wrapped in React **Error Boundaries**. This prevents a component-level error from crashing the entire application and allows a fallback UI to be displayed.
114 
115## Testing Commands
116 
117-   **Run the full application stack (API, Frontend, DB):**
118```bash
119    docker-compose up
120```
121-   **Build and run the stack from scratch:**
122```bash
123    docker-compose up --build
124```
125-   **Run backend tests:**
126```bash
127    cd api
128    poetry run pytest
129```
130-   **Run frontend linter:**
131```bash
132    cd frontend
133    npm run lint
134```
135-   **Run frontend dev server (with Hot Module Replacement):**
136```bash
137    cd frontend
138    npm install
139    npm run dev
140```
141 
142## Testing Guidelines
143 
144**Backend (`pytest`):**
145-   All test files are located in the `api/tests/` directory.
146-   Test files should be named following the `test_*.py` pattern.
147-   **Unit Tests**: Located in `api/tests/unit/`. These tests should focus on a single function or class and mock external dependencies (like database or network calls) where necessary.
148-   **Integration Tests**: Located in `api/tests/integration/`. These tests verify the interaction between different components of the backend, often involving database access.
149-   Fixtures are heavily used to set up test data and clients. For example, `admin_client` provides an authenticated API client.
150 
151Example backend test (`api/tests/unit/audit/test_views.py`):
152```python
153def test_get_audit_log_count(admin_client):
154    # When
155    response = admin_client.get("/api/v1/audit/count/")
156    # Then
157    assert response.status_code == 200
158    assert response.json()["count"] >= 0
159```
160 
161**Frontend (`Jest` & `TestCafe`):**
162-   **Unit/Component Tests (`Jest`)**: Test files should be co-located with the components they are testing (e.g., `Component.tsx` and `Component.test.tsx`). These tests should verify component rendering and behavior in isolation.
163-   **End-to-End Tests (`TestCafe`)**: E2E test scripts are located in the `frontend/e2e/` directory. These tests simulate real user workflows by interacting with the application in a browser.
164 
165## Security & Compliance
166 
167-   **Secrets Management**: **NEVER** hard-code secrets (API keys, passwords, tokens) in the source code. All secrets must be managed through environment variables. The `docker-compose.yml` file serves as a reference for required variables in local development.
168-   **Authentication**: The API uses a built-in authentication system to protect endpoints.
169-   **Authorization**: Permissions are managed using a Role-Based Access Control (RBAC) model to ensure users can only access resources appropriate for their role.
170-   **Vulnerability Reporting**: Any discovered security vulnerabilities must be reported privately to `support[at]flagsmith[dot]com`. Do not disclose them publicly in GitHub issues.
171 
172## Dependencies & Environment
173 
174The entire development environment is containerized with Docker to ensure consistency.
175 
176-   **Runtime Environment**: The primary way to run the project is via Docker. `docker-compose up` will start all required services (backend, frontend, database).
177-   **Backend Dependencies (Python)**:
178    -   Managed by **Poetry**.
179    -   Defined in `api/pyproject.toml`.
180    -   To install: `cd api && poetry install`
181    -   To add a new dependency: `cd api && poetry add <package-name>`
182-   **Frontend Dependencies (JavaScript/TypeScript)**:
183    -   Managed by **npm**.
184    -   Defined in `frontend/package.json`.
185    -   To install: `cd frontend && npm install`
186    -   To add a new dependency: `cd frontend && npm install <package-name>`
187-   **Environment Variables**: The application is configured using environment variables. See `docker-compose.yml` for a list of variables needed for local development.
188 
189## PR & Git Rules
190 
191The project follows a standard GitHub feature-branch workflow.
192 
193-   **Branch Naming**: Branch names should be descriptive and prefixed with a type, such as `feature/`, `bugfix/`, or `chore/`. Example: `feature/new-audit-log-export`.
194-   **Commit Messages**: Commits should be atomic and have clear, descriptive messages explaining the "what" and "why" of the change.
195-   **Workflow**:
196    1.  First, create a GitHub Issue to discuss the proposed change.
197    2.  Create a feature branch from an up-to-date `main` branch.
198```bash
199        git checkout main
200        git pull origin main
201        git checkout -b feature/my-new-feature
202```
203    3.  Implement changes and add corresponding tests.
204    4.  Ensure all code is formatted and linted correctly.
205    5.  Push the branch to your fork and open a Pull Request (PR) against the `flagsmith/flagsmith:main` branch.
206    6.  The PR must be linked to the issue it resolves and must pass all Continuous Integration (CI) checks before it can be considered for merging.
207 
208## Documentation Standards
209 
210-   **System & User Documentation**: The public-facing documentation for users and administrators is maintained in the `/docs` directory and built with **Docusaurus**. Significant changes to functionality should be accompanied by updates to this documentation.
211-   **Code Documentation**:
212    -   **Python**: Use **docstrings** for public modules, classes, and functions to explain their purpose, arguments, and return values.
213    -   **TypeScript/React**: Use **TSDoc** comments (`/** ... */`) to document complex components, props, and functions.
214 
215## Common Patterns
216 
217-   **Backend: Service Layer Abstraction**: Avoid putting business logic directly in Django views. Abstract complex operations into service functions or model methods. This keeps views thin and focused on HTTP concerns.
218```python
219    # Good: Logic is in the model/manager
220    class AuditLogCount(APIView):
221        def get(self, request, *args, **kwargs):
222            # The 'how' is hidden from the view
223            count = AuditLog.objects.get_total_count()
224            return Response({'count': count})
225 
226    # Bad: Logic is coupled to the view
227    class AuditLogCount(APIView):
228        def get(self, request, *args, **kwargs):
229            # Complex filtering and counting logic here...
230            count = AuditLog.objects.filter(is_archived=False).count()
231            return Response({'count': count})
232```
233-   **Frontend: Declarative Data Fetching**: **ALWAYS** use the RTK Query service for all API interactions. This pattern centralizes data fetching logic, provides automatic caching, and simplifies component code by using hooks.
234```typescript
235    // In frontend/common/service.ts
236    getAuditLogCount: builder.query<{ count: number }, {}>({
237        query: () => ({ url: `audit/count/` }),
238    }),
239 
240    // In a React component
241    import { useGetAuditLogCountQuery } from 'common/service';
242 
243    const MyComponent = () => {
244      // The hook handles loading, error, and data states automatically
245      const { data } = useGetAuditLogCountQuery({});
246      return <div>Count: {data?.count}</div>;
247    }
248```
249-   **Full-Stack Development**: New features typically require coordinated changes in both the `api/` and `frontend/` directories. This involves adding a DRF endpoint, serializing data, adding the endpoint to the RTK Query service, and creating a React component to consume it.
250 
251## Agent Workflow / SOP
252 
253When approaching a task, follow this Standard Operating Procedure (SOP):
254 
2551.  **Analyze the Request**: Determine if the task is backend-only, frontend-only, or full-stack.
2562.  **Identify Key Files**:
257    -   **Backend**: Locate the relevant Django app in `api/`. Changes will likely involve `models.py`, `serializers.py`, `views.py`, and `urls.py`. Tests will be in `api/tests/`.
258    -   **Frontend**: For UI changes, find the component in `frontend/web/components/`. For data/state changes, the primary files are `frontend/common/service.ts` (API interaction) and `frontend/common/store.ts` (global UI state).
2593.  **Implement Backend Changes (if required)**:
260    -   Modify the Django model in `models.py` and create a migration (`poetry run python manage.py makemigrations`).
261    -   Create or update a serializer in `serializers.py` to control the JSON representation.
262    -   Create or update the view in `views.py`. Keep business logic out of the view.
263    -   Register the URL route in `urls.py`.
264    -   Write unit or integration tests in `api/tests/` to cover the new logic.
2654.  **Implement Frontend Changes (if required)**:
266    -   If a new API endpoint is involved, add it to the `builder` in `frontend/common/service.ts`.
267    -   In the relevant React component, use the auto-generated RTK Query hook (e.g., `useGetMyDataQuery`) to fetch or mutate data.
268    -   **Strictly avoid** using `fetch()` or `axios()` directly in components.
269    -   Update or create React components to display the new data or provide new functionality.
270    -   Add Jest unit tests for new components or complex logic.
2715.  **Format and Lint**: Before finalizing, run the formatters and linters to ensure code style compliance.
272    -   Backend: `black .` and `isort .` within the `api/` directory.
273    -   Frontend: `npm run lint` within the `frontend/` directory.
2746.  **Verify Locally**: Use `docker-compose up --build` to run the entire application and manually verify that your changes work as expected end-to-end.
275 
276## Few-Shot Examples
277 
278### Good: Following the RTK Query Pattern for Data Fetching
279 
280This example correctly uses the centralized RTK Query service to fetch data and display it in a component.
281 
282**1. Define the endpoint in `frontend/common/service.ts`:**
283```typescript
284// Good: The endpoint definition is centralized and declarative.
285getAuditLogCount: builder.query<{ count: number }, {}>({
286    query: () => ({
287        url: `audit/count/`,
288    }),
289}),
290```
291 
292**2. Use the generated hook in `frontend/web/components/AuditLogCounter.tsx`:**
293```typescript
294import React from 'react';
295import { useGetAuditLogCountQuery } from 'common/service';
296 
297// Good: The component is simple, declarative, and leverages the hook for all async logic.
298export const AuditLogCounter = () => {
299    const { data, isLoading, error } = useGetAuditLogCountQuery({});
300 
301    if (isLoading) return <div>Loading...</div>;
302    if (error) return <div>Error fetching count!</div>;
303 
304    return <h1>Total Audit Logs: {data?.count}</h1>;
305};
306```
307 
308### Bad: Bypassing the RTK Query Service Layer
309 
310This example violates the core architectural rule by making a direct API call from a component.
311 
312**`frontend/web/components/AuditLogCounter.tsx`:**
313```typescript
314import React, { useEffect, useState } from 'react';
315 
316// Bad: This component violates the rule against direct API calls.
317// It manually handles loading, error, and data states, which is redundant
318// and inconsistent with the rest of the application.
319export const AuditLogCounter = () => {
320    const [data, setData] = useState<{ count: number } | null>(null);
321    const [isLoading, setIsLoading] = useState(true);
322    const [error, setError] = useState<Error | null>(null);
323 
324    useEffect(() => {
325        // DO NOT DO THIS. Use the RTK Query service instead.
326        fetch('http://localhost:8000/api/v1/audit/count/')
327            .then(res => res.json())
328            .then(setData)
329            .catch(setError)
330            .finally(() => setIsLoading(false));
331    }, []);
332 
333    if (isLoading) return <div>Loading...</div>;
334    if (error) return <div>Error fetching count!</div>;
335 
336    return <h1>Total Audit Logs: {data?.count}</h1>;
337};
338 
339```