AGENTS.md — ReverseFlow

A concise, agent-focused guide for working on this repo. Prefer these commands and conventions. Keep READMEs for humans; put build/test details here for agents.

Project overview

Backend: Python (FastAPI), mitmproxy addon, SQLite/Postgres, WebSocket events
Frontend: Vite + React + Tailwind (served in dev; built to
```
web/dist
```
for tests/prod)
CLI:
```
reverseflow
```
(editable install)
Tests:
```
pytest
```
for backend; Vitest + Playwright for web
Docker:
```
docker compose up --build
```
(MITM: 8080, mitmweb: 8081, API: 8000, Dashboard: 3000)

Repo structure (key paths)

```
src/reverseflow/
```
— API, engines, mitm addon, plugins, models
```
web/
```
— UI (Vite/React)
```
tests/
```
— pytest suite
```
scripts/
```
— tooling (static server for Playwright, smoke runner)

Setup

Choose local dev, or Docker.

Local (Python + Node)

Python 3.11 recommended (>=3.9 supported). Node 18+.

Windows PowerShell:

```
python -m venv .venv
```
```
.\.venv\Scripts\Activate.ps1
```
```
pip install --upgrade pip
```
```
pip install -r requirements.txt
```
```
pip install -e .
```
```
npm ci
```

macOS/Linux:

```
python -m venv .venv
```
```
. .venv/bin/activate
```
```
pip install --upgrade pip
```
```
pip install -r requirements.txt
```
```
pip install -e .
```
```
npm ci
```

Initialize DB (once):

Windows:
```
reverseflow init_db
```
macOS/Linux:
```
reverseflow init_db
```

Docker (optional)

```
docker compose up --build
```
Ports: 8080 (MITM), 8081 (mitmweb), 8000 (API), 3000 (dashboard).

Run (dev)

Start proxy + API + UI dev:

```
reverseflow dev
```

Endpoints

Dashboard: http://localhost:3000
API docs: http://127.0.0.1:8000/docs
Health: http://127.0.0.1:8000/health/live
mitmweb: http://127.0.0.1:8081

Mobile device

Proxy to your machine at port 8080
Install/Trust mitmproxy CA via http://mitm.it

Tests

Run the smallest necessary scope first.

Backend (pytest):

All:
```
pytest -q
```

Single file:

pytest tests/unit/test_rule_engine.py -q

Common markers exist: unit, integration, smoke, websocket, rule_engine, etc.

Type checks & lint:

```
mypy src/reverseflow tests
```
```
black . --check
```
```
flake8
```

Frontend unit (Vitest):

```
npm run test:unit:run
```

Frontend E2E (Playwright):

Build once:
```
npm run build
```
Core:
```
npm run test:core
```
Pages:
```
npm run test:pages
```
Editors:
```
npm run test:editors
```
A11y:
```
npm run test:accessibility
```
All:
```
npm run test:all
```

Playwright details

Config:
```
playwright.config.ts
```

Static server:

node scripts/serve-static.js

expects

web/dist

— run

npm run build

first

Base URL:
```
http://127.0.0.1:5176
```

Smoke tests

Quick sweep:
```
npm run smoke
```
Full sweep:
```
npm run smoke:full
```

Code style & conventions

Python

Black line length 88 (pyproject)
Mypy strict; keep type hints on public functions
Flake8 clean
Only use
```
.py
```
files; do not add shebangs (no env/bin headers)

TypeScript/React

```
npm run type-check
```
for TS
```
npm run lint
```
(ESLint)
Prefer functional components and hooks; ensure a11y for UI elements

General

Small, focused changes; keep diffs minimal
Prefer explicit, readable code over cleverness
Avoid unnecessary names, verbosity, and boilerplate

Useful CLI

```
reverseflow start
```
— start mitmproxy (+ optional API)
```
reverseflow dev
```
— proxy + API + Vite UI (dev)
```
reverseflow init_db
```
/
```
reset_db
```

Diagnostics:

reverseflow stats

reverseflow list_plugins

reverseflow check_setup

Environment

See README “Configuration” for full table. Common vars (defaults in code):

MITM_PORT=8080

MITM_WEB_PORT=8081

API_PORT=8000

```
DATABASE_URL=sqlite:///./reverseflow.db
```

API_CORS_ORIGINS=http://localhost:3000,http://localhost:5173

PLUGINS_DIR=./plugins

ENABLED_PLUGINS=base_interceptor

ENABLE_PREMIUM_BYPASS=true

SAVE_RAW_TRAFFIC=true

Plugins

Drop custom plugins under
```
src/reverseflow/plugins/
```
Minimal example in README (AppAnalyzer)
Enable via
```
reverseflow dev
```
and Plugin browser

PR guidance (for agents)

Before commit: run

black --check

flake8

mypy

pytest -q

npm run type-check

npm run test:unit:run

For UI or e2e changes:
```
npm run build
```
then Playwright subset (see above)
Keep commits focused; update or add tests for your changes

Security/legal

Use on test devices/apps you own and where permitted
Protect secrets (
```
ADMIN_TOKEN
```
,
```
SECRET_KEY
```
)
Consider
```
SAVE_RAW_TRAFFIC=false
```
in sensitive environments
Do not commit generated certs, DBs, or large artifacts

Troubleshooting quick checks

No flows? Confirm device proxy to :8080 and CA trust via http://mitm.it; check TLS pinning on target app
UI can’t reach API? Ensure API at 127.0.0.1:8000; Vite dev proxies
```
/api
```
+
```
/ws
```
Playwright fails to start server? Run
```
npm run build
```
(creates
```
web/dist
```
)
Windows
```
mitmdump
```
not found?
```
pip install mitmproxy
```
, restart shell to refresh PATH

Notes for coding agents

Prefer smallest verification runs (single test file, unit tests first)
Respect existing strict typing/lint settings; fix before submitting
On Windows, don’t chain with
```
&&
```
— run commands on separate lines
Keep changes minimal and reversible; avoid broad refactors without need

AGENTS.md — ReverseFlow

A concise, agent-focused guide for working on this repo. Prefer these commands and conventions. Keep READMEs for humans; put build/test details here for agents.

Project overview

Backend: Python (FastAPI), mitmproxy addon, SQLite/Postgres, WebSocket events
Frontend: Vite + React + Tailwind (served in dev; built to
```
web/dist
```
for tests/prod)
CLI:
```
reverseflow
```
(editable install)
Tests:
```
pytest
```
for backend; Vitest + Playwright for web
Docker:
```
docker compose up --build
```
(MITM: 8080, mitmweb: 8081, API: 8000, Dashboard: 3000)

Repo structure (key paths)

```
src/reverseflow/
```
— API, engines, mitm addon, plugins, models
```
web/
```
— UI (Vite/React)
```
tests/
```
— pytest suite
```
scripts/
```
— tooling (static server for Playwright, smoke runner)

Setup

Choose local dev, or Docker.

Local (Python + Node)

Python 3.11 recommended (>=3.9 supported). Node 18+.

Windows PowerShell:

```
python -m venv .venv
```
```
.\.venv\Scripts\Activate.ps1
```
```
pip install --upgrade pip
```
```
pip install -r requirements.txt
```
```
pip install -e .
```
```
npm ci
```

macOS/Linux:

```
python -m venv .venv
```
```
. .venv/bin/activate
```
```
pip install --upgrade pip
```
```
pip install -r requirements.txt
```
```
pip install -e .
```
```
npm ci
```

Initialize DB (once):

Windows:
```
reverseflow init_db
```
macOS/Linux:
```
reverseflow init_db
```

Docker (optional)

```
docker compose up --build
```
Ports: 8080 (MITM), 8081 (mitmweb), 8000 (API), 3000 (dashboard).

Run (dev)

Start proxy + API + UI dev:

```
reverseflow dev
```

Endpoints

Dashboard: http://localhost:3000
API docs: http://127.0.0.1:8000/docs
Health: http://127.0.0.1:8000/health/live
mitmweb: http://127.0.0.1:8081

Mobile device

Proxy to your machine at port 8080
Install/Trust mitmproxy CA via http://mitm.it

Tests

Run the smallest necessary scope first.

Backend (pytest):

All:
```
pytest -q
```

Single file:

pytest tests/unit/test_rule_engine.py -q

Common markers exist: unit, integration, smoke, websocket, rule_engine, etc.

Type checks & lint:

```
mypy src/reverseflow tests
```
```
black . --check
```
```
flake8
```

Frontend unit (Vitest):

```
npm run test:unit:run
```

Frontend E2E (Playwright):

Build once:
```
npm run build
```
Core:
```
npm run test:core
```
Pages:
```
npm run test:pages
```
Editors:
```
npm run test:editors
```
A11y:
```
npm run test:accessibility
```
All:
```
npm run test:all
```

Playwright details

Config:
```
playwright.config.ts
```

Static server:

node scripts/serve-static.js

expects

web/dist

— run

npm run build

first

Base URL:
```
http://127.0.0.1:5176
```

Smoke tests

Quick sweep:
```
npm run smoke
```
Full sweep:
```
npm run smoke:full
```

Code style & conventions

Python

Black line length 88 (pyproject)
Mypy strict; keep type hints on public functions
Flake8 clean
Only use
```
.py
```
files; do not add shebangs (no env/bin headers)

TypeScript/React

```
npm run type-check
```
for TS
```
npm run lint
```
(ESLint)
Prefer functional components and hooks; ensure a11y for UI elements

General

Small, focused changes; keep diffs minimal
Prefer explicit, readable code over cleverness
Avoid unnecessary names, verbosity, and boilerplate

Useful CLI

```
reverseflow start
```
— start mitmproxy (+ optional API)
```
reverseflow dev
```
— proxy + API + Vite UI (dev)
```
reverseflow init_db
```
/
```
reset_db
```

Diagnostics:

reverseflow stats

reverseflow list_plugins

reverseflow check_setup

Environment

See README “Configuration” for full table. Common vars (defaults in code):

MITM_PORT=8080

MITM_WEB_PORT=8081

API_PORT=8000

```
DATABASE_URL=sqlite:///./reverseflow.db
```

API_CORS_ORIGINS=http://localhost:3000,http://localhost:5173

PLUGINS_DIR=./plugins

ENABLED_PLUGINS=base_interceptor

ENABLE_PREMIUM_BYPASS=true

SAVE_RAW_TRAFFIC=true

Plugins

Drop custom plugins under
```
src/reverseflow/plugins/
```
Minimal example in README (AppAnalyzer)
Enable via
```
reverseflow dev
```
and Plugin browser

PR guidance (for agents)

Before commit: run

black --check

flake8

mypy

pytest -q

npm run type-check

npm run test:unit:run

For UI or e2e changes:
```
npm run build
```
then Playwright subset (see above)
Keep commits focused; update or add tests for your changes

Security/legal

Use on test devices/apps you own and where permitted
Protect secrets (
```
ADMIN_TOKEN
```
,
```
SECRET_KEY
```
)
Consider
```
SAVE_RAW_TRAFFIC=false
```
in sensitive environments
Do not commit generated certs, DBs, or large artifacts

Troubleshooting quick checks

No flows? Confirm device proxy to :8080 and CA trust via http://mitm.it; check TLS pinning on target app
UI can’t reach API? Ensure API at 127.0.0.1:8000; Vite dev proxies
```
/api
```
+
```
/ws
```
Playwright fails to start server? Run
```
npm run build
```
(creates
```
web/dist
```
)
Windows
```
mitmdump
```
not found?
```
pip install mitmproxy
```
, restart shell to refresh PATH

Notes for coding agents

Prefer smallest verification runs (single test file, unit tests first)
Respect existing strict typing/lint settings; fix before submitting
On Windows, don’t chain with
```
&&
```
— run commands on separate lines
Keep changes minimal and reversible; avoid broad refactors without need

AGENTS.md — ReverseFlow

AGENTS.md — ReverseFlow

Project overview

Setup

Local (Python + Node)

Docker (optional)

Run (dev)

Tests

Code style & conventions

Useful CLI

Environment

Plugins

PR guidance (for agents)

Security/legal

Troubleshooting quick checks

Notes for coding agents

Related Skills

Markdown Converter

Nano Banana Pro

1password

AGENTS.md — ReverseFlow

Project overview

Setup

Local (Python + Node)

Docker (optional)

Run (dev)

Tests

Code style & conventions

Useful CLI

Environment

Plugins

PR guidance (for agents)

Security/legal

Troubleshooting quick checks

Notes for coding agents