Project Data Model#

A project is the primary scoping entity in agenta, grouping apps, test sets, evaluator configs, and other resources under a single tenant boundary. Projects are created and managed entirely on the backend — the frontend has no UI for creating or modifying them.

Data Shape#

The canonical API shape is ProjectsResponse, shared between the backend Pydantic model 1 and the frontend TypeScript interface 2:

The database model ProjectDB stores id, project_name, is_default, created_at, updated_at, with optional FK references to workspaces and organizations. It has cascade-delete relationships to AppDB, EvaluatorConfigDB, and TestSetDB, meaning deleting a project removes all dependent resources 3.

API Layer#

The sole public endpoint is GET /projects, defined in projects_router.py. Its behavior differs by deployment mode:

• OSS: Returns a single-element list for the project associated with request.state.project_id — the project ID is injected by middleware, not selected by the user 4.
• EE: Returns all projects the authenticated user is a member of, fetched via db_manager_ee.fetch_project_memberships_by_user_id 5.

There are no POST, PUT, or DELETE endpoints in the router — project lifecycle is managed outside this API surface.

Frontend Integration#

The frontend fetches projects via fetchAllProjects(), which issues GET /projects. Results are held in ProjectContext, accessible throughout the app via the useProjectData() hook.

Key context values 6:

• project — the currently active ProjectsResponse object.
• projectId — the active project's UUID; falls back to DEFAULT_UUID ("00000000-0000-0000-0000-000000000000") when no project is resolved 7.
• isProjectId — true only when loading is complete and a valid project ID exists 8.
• refetch / reset — used during auth lifecycle events (login, logout, workspace switch).

Project selection logic: In OSS, the first project returned by the API is used. In demo/EE mode, the project is matched by workspace_id against the selected organization's default workspace 9.

The context re-fetches when doesSessionExist or selectedOrg changes 10, so project data stays in sync with workspace/org switches.

Limitations#

• No UI for project CRUD. The frontend service layer only exposes fetchAllProjects — there are no createProject, updateProject, or deleteProject calls 11.
• OSS is single-project. The OSS backend unconditionally returns one project per request; multi-project support is an EE feature 4.
• projectId is always present. Components that guard on isProjectId (e.g., ProtectedRoute, TestsetTable) will block rendering until a project is resolved. Falling back to DEFAULT_UUID prevents null-safety issues but can mask missing project state.

Key Files#