Projects

Scope captures, replays, decoders, and bookmarks per target — like codebases in an IDE.

A project is the top-level scope for everything you collect and produce in Traffic Jam: capture sessions and folders, replay history, decode pipelines and scripts, protobuf schemas and bindings, route model rules, endpoint annotations, client certificates, fingerprint profiles, canaries, and bookmarks. Switching projects swaps the whole workspace at once — the same way you switch codebases in an IDE.

Use one project per target or engagement (for example, goldapple mobile and partner-api audit) so evidence, decoders, and notes never mix.

Managing projects

The project switcher sits at the top of the left sidebar. From its menu you can:

Switch — click a project to make it active. The capture library, analysis tabs, bookmarks, and all reverse-engineering registries reload under the new scope.
New project… — creates a project and switches to it immediately. The fresh project starts empty except for the built-in decode scripts, which are seeded per project.
Rename — renames a project without touching its contents.
Delete — removes the project and everything inside it (captures, replays, decoders, bookmarks) via a cascade. The active project cannot be deleted; switch away first. The action asks for confirmation and cannot be undone.

The active project is remembered across restarts and shown as a badge in the workspace header.

How scoping works

Every entity table in the SQLite database carries a project_id foreign key to the projects table (ON DELETE CASCADE, which is what makes delete-by-project total). The backend resolves the active project from the X-Traffic-Jam-Project request header in the withActiveProject middleware; routes under /api/projects and /api/health are the only unscoped endpoints.

Route	Scope
`GET/POST /api/projects`, `PATCH/DELETE /api/projects/{id}`	Unscoped (project management)
`GET/PUT/DELETE /api/projects/active`	Unscoped (selects the scope)
`PUT /api/projects/{id}/bookmarks-import`	Unscoped (bulk bookmark import)
Everything else under `/api`	Requires an active project; scoped queries return `404` for rows owned by other projects

A fresh database seeds a Default project, and the backend activates it on startup, so scripts that never send the project header keep working.

Bookmarks moved to the backend

Bookmarks (request pins and capture pins) used to live in browser localStorage; they are now stored in the database per project (request_bookmarks / capture_bookmarks tables) and managed through /api/bookmarks. On first launch after the upgrade, the app offers the legacy localStorage bookmarks once to the first project you activate via PUT /api/projects/{id}/bookmarks-import, then removes the legacy document.

[!WARNING] Projects are a breaking change. The v0.4 database is a new file (traffic-jam-v2.sqlite3); the old traffic-jam.sqlite3 is left untouched but is no longer read.