Skip to content

Commit 4debb9c

Browse files
groovecodergroovecoder
committed
start agents.md to guide coding assistants
1 parent c1add09 commit 4debb9c

File tree

11 files changed

+769
-0
lines changed

11 files changed

+769
-0
lines changed

‎.agents/agents.backend.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Backend Development Guide
2+
3+
Backend guidance for Relay python Django codebase.
4+
5+
See [agents.md](agents.md) for project overview and global principles.
6+
7+
## Technology Stack
8+
9+
- **Backend**: Python 3, Django, Django REST Framework (DRF)
10+
- **Database**: PostgreSQL via `psycopg[c]` and Django ORM models
11+
- **API**: REST API served via DRF
12+
- **Caching**: Redis via django-redis
13+
- **Email**: AWS SES/SNS/SQS via boto3
14+
- **Phone**: Twilio
15+
- **Auth**: Mozilla Accounts OAuth via django-allauth
16+
- **Testing**: pytest-django, model-bakery, responses library
17+
- **Code Quality**: Ruff, mypy (strict mode)
18+
19+
## Common Commands
20+
21+
```bash
22+
# Code quality
23+
ruff check . # Lint
24+
ruff format . # Format
25+
mypy . # Type check
26+
27+
# Testing
28+
pytest # All tests
29+
pytest api/ # Test specific app
30+
pytest -k test_name # Run specific test
31+
```
32+
33+
## Django Apps Structure
34+
35+
The backend is organized into Django apps.
36+
37+
Check for an `.agents.md` file in an app directory for detailed guidance for that app.
38+
39+
## Runtime data for front-end
40+
41+
1. **Django serves static files** via Whitenoise
42+
2. **Frontend fetches runtime config** from `/api/runtime_data/` endpoint
43+
44+
## Runtime operations
45+
46+
1. **Email forwarding** happens via background process (NOT in web request cycle)
47+
2. **Phone masking** happens synchronously in web requests
48+
49+
## Django Migrations
50+
51+
### Adding New Fields
52+
53+
New columns need database default or allow `NULL` to prevent errors when old code runs against new database.
54+
55+
**Why:** During rollout, old code runs against new database. Omitted columns in INSERT statements must have defaults.
56+
57+
**Example:**
58+
59+
```python
60+
# Good
61+
new_field = models.CharField(max_length=100, default="")
62+
# or
63+
new_field = models.CharField(max_length=100, null=True, blank=True)
64+
65+
# Bad (will fail during rollout)
66+
new_field = models.CharField(max_length=100)
67+
```
68+
69+
### Deleting Fields/Models
70+
71+
**Rollout process:**
72+
73+
1. Remove all references in code
74+
2. Deploy code changes to production
75+
3. Then remove from `models.py` and create migration
76+
4. Deploy model changes and migration
77+
78+
**Why:** Prevents errors when code references deleted columns during rollout.
79+
80+
## Management Commands
81+
82+
Django apps have management commands in their `management/commands/` directory. See app-specific .agents.md files for detailed guidance on each app's management commands.
83+
84+
## Backend Testing
85+
86+
See [agents.testing.md](agents.testing.md) for full testing guidance.
87+
88+
**Quick reference:**
89+
90+
```bash
91+
pytest # Run all tests
92+
pytest api/ # Test specific app
93+
pytest -k test_name # Run specific test
94+
```
95+
96+
**Framework:** pytest with pytest-django
97+
**Fixtures:** model-bakery for model factories
98+
**Mocking:** responses library for HTTP mocks
99+
**Coverage:** coverage.py with HTML reports
100+
101+
## Code Quality Guidelines
102+
103+
See [.agents.md](.agents.md) for global code quality rules.
104+
105+
**Backend-specific:**
106+
107+
- Type hints required (mypy strict mode)
108+
- Use Django ORM over raw SQL
109+
- Prefer built-in functions over custom implementations
110+
- Extract functions when indented too many levels (Python-specific)
111+
112+
## Further Reading
113+
114+
### App-Specific Guidance
115+
116+
- [privaterelay/.agents.md](privaterelay/.agents.md) - Core Django, settings, middleware, management commands
117+
- [api/.agents.md](api/.agents.md) - REST API, authentication, serializers
118+
- [emails/.agents.md](emails/.agents.md) - Email masking, AWS integration, metrics
119+
- [phones/.agents.md](phones/.agents.md) - Phone masking, Twilio integration
120+
121+
### Cross-Cutting Guidance
122+
123+
- [.agents.md](.agents.md) - Project overview and global principles
124+
- [.agents/agents.frontend.md](.agents/agents.frontend.md) - Frontend development
125+
- [.agents/agents.testing.md](.agents/agents.testing.md) - Testing guidance
126+
127+
### Additional Resources
128+
129+
- `docs/` - Comprehensive architecture documentation
130+
- `README.md` - Full setup instructions

‎.agents/agents.frontend.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Frontend Development Guide
2+
3+
Frontend guidance for Firefox Private Relay Next.js/React/TypeScript codebase.
4+
5+
See [./agents.md](./agents.md) for project overview and global principles.
6+
7+
## Technology Stack
8+
9+
- **Frontend**: TypeScript, React, Next.js (static export)
10+
- **Styling**: SCSS with CSS modules, Protocol design system
11+
- **Data Fetching**: SWR (stale-while-revalidate)
12+
- **i18n**: Fluent (@fluent/react)
13+
- **Accessibility**: React Aria
14+
- **Testing**: Jest, React Testing Library, jest-axe
15+
- **Code Quality**: ESLint, Prettier, StyleLint
16+
17+
## Common Commands
18+
19+
```bash
20+
cd frontend
21+
npm run dev # Dev server on :3000 (hot reload)
22+
npm run watch # Production build with watch
23+
npm run build # Static HTML export to /frontend/out/
24+
npm test # Jest tests
25+
npm run lint # All linters
26+
npm run dev:mocked # Dev with MSW mocking
27+
```
28+
29+
## Frontend Patterns
30+
31+
### Static HTML Export (No SSR)
32+
33+
Next.js generates static HTML served by Django/Whitenoise. Build output in `/frontend/out/`. All pages must be statically exportable. No `getServerSideProps`.
34+
35+
### Single Build for All Environments
36+
37+
Frontend built once, deployed to dev/stage/prod. Environment-specific config fetched at runtime from `/api/runtime_data/` via `useRuntimeData` hook. See [agents.md](./agents.md).
38+
39+
### Runtime Config
40+
41+
Use `useRuntimeData` hook to fetch feature flags, environment URLs, and API config. To add config: update `api/views/privaterelay.py` (backend) and `/frontend/src/hooks/api/runtimeData.ts` (frontend types).
42+
43+
### SWR for Data Fetching
44+
45+
Create custom hooks in `/frontend/src/hooks/api/` for each API endpoint.
46+
47+
## Mock Data for Development
48+
49+
Mock data in `frontend/__mocks__/api/mockData.ts`. Available mock users: `empty`, `onboarding`, `some`, `full`.
50+
51+
**Usage:** Append `?mockId=<mockId>` to URL or run `npm run dev:mocked`.
52+
53+
**Updating:** Change type definitions in `/frontend/src/hooks/api/` first, then update mock data. TypeScript guides you to stale mocks.
54+
55+
## CSS/Styling
56+
57+
Follow [Protocol design system](https://protocol.mozilla.org) and [CSS coding guide](https://protocol.mozilla.org/docs/css-guide.html).
58+
59+
## Translations (i18n)
60+
61+
Translations in git submodule at `privaterelay/locales/`. Use Fluent (@fluent/react) with `<Localized>` component.
62+
63+
**Update translations:** `git submodule update --remote`
64+
65+
**Add new strings:** Use `frontend/pendingTranslations.ftl` temporarily, then create PR to [fx-private-relay-l10n](https://github.com/mozilla-l10n/fx-private-relay-l10n). Remove temporary strings after merge to avoid test failures.
66+
67+
## Frontend Testing
68+
69+
See [agents.testing.md](agents.testing.md) for details. Use Jest with React Testing Library and jest-axe for accessibility. Tests co-located with components (`component.test.tsx`). Test user behavior, not implementation details.
70+
71+
## Code Organization
72+
73+
- Components use CSS modules (`component.module.scss`)
74+
- Data fetching via custom SWR hooks in `/hooks/`
75+
- Tests co-located with components
76+
- Mock data in `__mocks__/` for different user states
77+
78+
## Code Quality Guidelines
79+
80+
See [agents.md](agents.md) for global rules. Use TypeScript strict mode, functional components, hooks for state/effects, and React Aria for accessibility.
81+
82+
## Further Reading
83+
84+
- [agents.md](agents.md) - Project overview
85+
- [agents.backend.md](agents.backend.md) - Backend API
86+
- [agents.testing.md](agents.testing.md) - Testing guidance
87+
- [Protocol Design System](https://protocol.mozilla.org)

‎.agents/agents.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# agents.md
2+
3+
This file provides guidance to coding agents when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Firefox Private Relay is a Mozilla privacy service that generates masked email addresses and phone numbers. The project uses Django (Python) for the backend API and Next.js (TypeScript/React) for the frontend, with static HTML export served by Django. The production site is https://relay.firefox.com
8+
9+
**Tech stack:** Python, Django, Django REST Framework, PostgreSQL, Redis, AWS: SES/SNS/SQS, Twilio, Mozilla Accounts OAuth, TypeScript, React, Next.js (static export),
10+
11+
## Where to Find Guidance
12+
13+
Working on different parts of the codebase? Start here:
14+
15+
- **Backend (Django/Python/API)** → See [agents.backend.md](agents.backend.md)
16+
- **Frontend (Next.js/React/TypeScript)** → See [agents.frontend.md](agents.frontend.md)
17+
- **Testing & QA** → See [agents.testing.md](agents.testing.md)
18+
19+
## Quick Commands
20+
21+
```bash
22+
# Tests
23+
pytest # Backend
24+
cd frontend && npm test # Frontend
25+
26+
# Code quality
27+
ruff check . && ruff format . # Python
28+
cd frontend && npm run lint # Frontend
29+
```
30+
31+
## Global Principles
32+
33+
These constraints apply across the entire codebase:
34+
35+
### Single Frontend Static HTML Export
36+
37+
The frontend is built **once** and deployed to **all environments** (dev, stage, prod). Environment-specific values **cannot be baked into the build**. See "Environment-specific configuration" in [agents.backend.md](agents.backend.m) for more details. Next.js generates static HTML served by Django/Whitenoise. No server-side rendering. Dynamic routes must be handled carefully.
38+
39+
### Translations Submodule
40+
41+
`privaterelay/locales/` is a separate git repository. Always clone with `--recurse-submodules`. Updated automatically by daily jobs.
42+
43+
### Code Quality
44+
45+
- Use clear variable names.
46+
- Extract functions when code appears 3+ times (not 2).
47+
- Delete unused imports, functions, commented-out code immediately.
48+
- No emoji in code or comments.
49+
- Type hints required (Python mypy strict mode).
50+
51+
#### Code comments
52+
53+
Add comments only for:
54+
55+
- **Why, not what** - Explain reasoning, not mechanics
56+
- **Context** - Business rules, edge cases, non-obvious decisions
57+
- **Warnings** - Performance gotchas, accessibility considerations
58+
59+
Skip comments that:
60+
61+
- Restate what the code already says
62+
- Describe obvious operations
63+
- Would be better expressed as better variable names
64+
65+
Do NOT use emoji in comments.
66+
67+
## Getting Help
68+
69+
- Check area-specific files linked above for detailed guidance
70+
- See `README.md` for full setup instructions
71+
- See `docs/` for architecture documentation

‎.agents/agents.testing.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Testing & QA Guide
2+
3+
Testing guidance for Firefox Private Relay.
4+
5+
See [.agents/agents.md](.agents/agents.md) for project overview and global principles.
6+
7+
## Testing Overview
8+
9+
- **Backend:** pytest with pytest-django, model-bakery, responses library
10+
- **Frontend:** Jest with React Testing Library, jest-axe, MSW
11+
- **E2E:** Playwright (Chrome and Firefox)
12+
13+
## Quick Reference
14+
15+
Run tests in order (fast → slow):
16+
17+
```bash
18+
ruff check . # Backend linting
19+
mypy . # Type checking
20+
cd frontend && npx --no-install lint-staged --cwd .. # Frontend linting
21+
cd frontend && npm run lint # Frontend linting
22+
cd frontend && npm test # Frontend tests
23+
pytest # Backend tests
24+
```
25+
26+
## E2E Testing
27+
28+
**Framework:** Playwright with Page Object Model. Specs in `/e2e-tests/specs/`, page objects in `/e2e-tests/pages/`.
29+
30+
**Commands:**
31+
32+
```bash
33+
cd frontend
34+
npm run test:e2e # Default
35+
npm run test:local # http://127.0.0.1:8000 (requires backend + frontend build)
36+
npm run test:dev # https://relay-dev.allizom.org
37+
npm run test:stage # https://relay.allizom.org
38+
npm run test:prod # https://relay.firefox.com (read-only)
39+
```
40+
41+
**Local testing:** Requires backend running and frontend built. Fast feedback loop.
42+
43+
**Dev/Stage:** Tests against deployed environments. Requires credentials.
44+
45+
**Production:** Read-only smoke tests only.
46+
47+
## Testing Checklist for PRs
48+
49+
- [ ] Linting: `ruff check .` and `cd frontend && npx --no-install lint-staged --cwd ..`
50+
- [ ] Type checking: `mypy .`
51+
- [ ] Frontend tests: `cd frontend && npm test`
52+
- [ ] Backend tests: `pytest`
53+
- [ ] New features have tests
54+
55+
## Coverage Reports
56+
57+
**Backend:** `pytest --cov --cov-report=html` → `htmlcov/index.html`
58+
59+
**Frontend:** `cd frontend && npm test -- --coverage` → `coverage/lcov-report/index.html`
60+
61+
## CI/CD Testing
62+
63+
Tests run in GitHub Actions on every PR push and before merge. Order: linting → type checking → unit tests → E2E (stage). See `.github/workflows/`.
64+
65+
## Further Reading
66+
67+
- [.agents/agents.md](.agents/agents.md) - Project overview
68+
- [agents.backend.md](agents.backend.md) - Backend patterns
69+
- [agents.frontend.md](agents.frontend.md) - Frontend patterns
70+
- [pytest docs](https://docs.pytest.org/), [React Testing Library](https://testing-library.com/react), [Playwright](https://playwright.dev/)

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,5 @@ gcp_key.json
2222
version.json
2323
docs/api_schema.yaml
2424
docs/api_docs.html
25+
26+
.claude/settings.local.json

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Read the following file immediately as it's relevant to all workflows: @.agents/agents.md.

‎CLAUDE.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Agent Lightbeam - Project Context
2+
3+
This file is automatically loaded by Claude Code.
4+
5+
@.agents/agents.md

0 commit comments

Comments
 (0)