Codebase map

This map shows where things live in the TestLookup code, for contributors who want to follow or change a feature. A module named here exists in the code of this version. Whether its feature is turned on in a given installation is a separate question.

Backend

Start at backend/app/main.py and at register_routers in backend/app/bootstrap.py. Or find the endpoint in the API reference: the generated endpoint index on GitHub links each route to the code that handles it. From the route, follow the request in this order:

1. Its request format.
2. The checks on role and access.
3. The service that holds the logic.
4. The SQLAlchemy model, or the MongoDB or file-storage client.
5. The serializer that formats the response.
6. The tests.

Services share the application’s models and run in the same processes. A file name that ends in _service does not mean a separately deployed service.

Project export and import are not in the area map below. They live in backend/app/services/project_export_*.py and project_import_*.py, and their background jobs are in project_data_job_service.py. Four tests guard them:

• backend/tests/test_project_export_classification.py covers every table that belongs to a project.
• test_project_export_documents.py covers every MongoDB collection.
• test_project_export_objects.py covers the keys of stored files.
• test_project_import_side_effect_free.py fails if an import could reach the code that receives results, sends notifications or webhooks, calls a model or updates search.

Frontend

Use frontend/src/App.tsx to find a page’s route. Then follow the page and its components through hooks, state, permissions, shared types and frontend/src/services/api.ts. Check the screen against the API’s response format, or against what the handler really returns. Include the loading, empty, partial, error and not-allowed states.

• The sidebar is built from frontend/src/components/layout/navConfig.ts.
• Old addresses are redirected by frontend/src/routing/legacyRedirects.tsx.
• The in-app user guide, served at /docs, lives in frontend/src/content/guide/.

Workers and agents

To follow background work, start where the job is created and the queue it is sent to. Then follow it through:

• the Celery task’s entry point;
• the event-loop and client set-up;
• leases and retries;
• outboxes and child workers;
• workflow definitions and tool rules;
• saving the results, and the catch-up jobs.

Which queues exist, and which workers read them, differ between install modes. Agent child work needs its own worker for the agent_children queue. The generated worker task list on GitHub records each task’s route, queue and schedule as written in the code. It does not show which workers are running.

CLI, SDKs and MCP server

The command-line tool (CLI), the code libraries (SDKs) for each language and the MCP server each use a different part of the API. Read cli/testlookup_cli, client and mcp separately, because each has its own packaging, sign-in, live updates, retries and versions. Not every client supports every report format the backend can read. None of the clients is published to a package registry yet, so install them from a copy of the repository. The MCP server accepts sign-in tokens (JWT access tokens), but not API keys.

What the code contains

In this version, the repository holds 7,032 files. The API reference, the data dictionary (160 tables) and the generated worker task list link each route, table and task to its source file. All three are generated from the code of this version.

Changing a feature

For a change, follow the route through each part it touches: its data format, service, stored data or migration, worker jobs and outside effects, serializer, the code that uses it, and its tests. Keep these working:

• the limits on which projects each user can reach;
• the stages each record goes through;
• safe repeats of the same request;
• the activity log and monitoring;
• the generated references.

In reviews, link to the code at a fixed commit, so that later changes to the code do not change what you pointed to.

Architecture maps

The tables below show which folders, areas and parts of the code hold each feature.

Repository map

Folder or files	What it holds
backend/app/main.py, bootstrap.py	Start-up, middleware, route registration, and the health and monitoring set-up
backend/app/core	Settings, sign-in, role and access checks, release rules, security, logging and metrics
backend/app/routers	The HTTP and WebSocket endpoints. Start with the API index to find a feature’s paths
backend/app/models	Database models, public data formats, fixed lists of values, AI input and output formats, evidence formats and serializers
backend/app/db	Clients for PostgreSQL, MongoDB and Redis, file storage, and the checks that refuse work when TestLookup is overloaded
backend/app/services	The logic that coordinates each feature. A name ending in _service does not mean it is deployed on its own
backend/app/agents, tools	Agent workflow steps, the Investigator and Fixer agents, and adapters for evidence and tools
backend/app/streams	Reading live events, sending them to viewers, and the streaming protocol
backend/app/worker	Celery task entry points, schedules, queue routing, event-loop set-up and training tasks
backend/migrations	Alembic database updates (migrations) and data backfills. These decide how a database is upgraded
backend/models, backend/scripts	Model files and their settings, and backend maintenance tools
backend/tests	Unit, architectural, regression and integration tests
frontend/src/pages, components	Routed feature screens and reusable UI
frontend/src/services, hooks, store, types, utils, config	API calls and data formats, polling and state, permissions, and shared display logic
frontend/tests	Browser tests and exploratory checks. The config shows whether a test runs against a live server or a mock
cli/testlookup_cli	Command groups (Typer), profiles, API calls and output
client	The Python reporter, the JavaScript, Java and Go integrations, CI details and examples
mcp	The FastMCP adapter, API client, sign-in check, tools, resources, prompts and tests
scripts	Setup, sample data, release and backup tasks, quality checks that must not get worse, and documentation generators
docker-compose*.yml, Makefile, install.sh	Start-up for local, release, VM and offline installs, and common operator tasks
k8s, homelabsetup, openshiftsetup	The Kubernetes base and overlays, and the K3s and OpenShift install scripts
infra, deploy	Cloud and monitoring files, and the list of images
.github/workflows	CI, release, infrastructure and deployment automation
benchmarks, samples	Sample data for performance and AI quality checks, and example reports
architecture, docs, user-guide	Detailed architecture guides, maintainer docs and the operator guide. The end-user guide is in frontend/src/content/guide

Area and service map

Area	Main services and entry points	Data it keeps and who uses it
Receiving results	ingestion, ingestion_pipeline, format parsers, safe_archive, upload_status	Runs, test results and history, MongoDB evidence, and upload records in Redis
Live	stream_service, ws_event_ingest, live_session_drainer, live_run_recovery_service	Redis stream and session, then the saved run, then live updates to the screens
Intelligence	analysis_router, rules_engine, ml, training, run_intelligence_service	AI analyses, summaries, and where each pipeline result came from
Agent governance	agent_catalog, agent_config_resolver, agent_planner, workflow_definition_service, action_policy	Settings versions, and records of agent calls, pipelines, steps and actions
Reliability	pipeline_lease, retry_policy, pipeline_retry_config, run_downstream_outbox, tombstones	Saved status, retries, removing duplicates, and catch-up jobs
Evidence and reports	evidence_*, decision_report_*, report_composition_service, summary_report_service	Evidence links that never change, report attempts, and HTML, PDF, share links and exports
Reviews	review_request_service, review_envelope, review_supervisor, report_distribution_policy	Which report a review covers, its state (accepted, rejected or replaced), and a record of where it was shared
Release	release_*, policy_evaluator_service, policy_resolution, run_diff_service	Which runs belong to a release, phases, totals, and decisions that are only ever added to
Test management	test_management_*, test_case_lifecycle_service, suite_*, duplicate_detection_service	Written test cases, plans, strategies, each test’s permanent identity, and reviews
Flaky tests and performance	flaky_*, quarantine_*, perf_regression_service, performance_budgets	Usual timings to compare against, quarantine state, signals and coaching
Identity and settings	mfa_service, sso_service, scim_service, refresh_token_service, feature_flags, secret_service	Users, tokens, membership, project policies, audit
External integrations	connectors, jira_client, GitHub/GitLab services, notification, webhook_service	Outside services’ APIs, delivery attempts and their records, and retries
Knowledge and search	knowledge_*, rag_*, search_*, semantic_search	Source documents and their chunks, the search index, generated drafts and their sources
Administration	retention_service, run_deletion_service, deletion_job_service, storage_accounting_service	Purge rules, markers for deleted runs, how long stored files are kept, and operations reports

Dependency directions

Request handlers use the core access checks, data formats, database models and services. Services use the storage clients and other services. Agent workflow steps call those services and tools under the rules set for each run. Celery tasks call the same shared code. The web app, the command-line tool and the MCP server use the REST API, and the code libraries (SDKs) also send live events and batches. Database migrations depend on the history of the database layout, not on what uses the API.

The libraries each part depends on are listed, with their versions, in the backend requirements, the frontend package file, the CLI package, the client package and the MCP requirements. The frontend uses React Router, Axios, SWR, Zustand, Tailwind, Radix, chart libraries and Markdown rendering. The backend uses FastAPI, Pydantic, SQLAlchemy, Celery, Redis, Motor, file-storage clients, LangChain, LangGraph, optional Chroma and export libraries. Read the files for version numbers instead of copying them from old badges.

To make a change, follow it in this order:

1. The route.
2. Its input format.
3. The service.
4. The database model and migration.
5. Any worker job or outside effect.
6. The serializer.
7. The frontend or client code that uses it.
8. The tests of its behaviour.

Components and ownership

Component	Responsibility	Key implementation
React 19 and TypeScript web app	Pages, controls that depend on the user’s role, polling and live updates, charts, and the screens for reviewing and writing	frontend/src/App.tsx, frontend/src/services/api.ts
FastAPI API	Checks each request, sign-in and access, coordinates the work and formats the response	backend/app/main.py, backend/app/bootstrap.py, backend/app/routers
Domain services	Receiving results, identity, releases, governance, reporting, retention and integrations	backend/app/services
Celery workers	Read and save test results, run analysis pipelines, send notifications and clean up	backend/app/worker/tasks.py, backend/app/worker/celery_app.py
Beat	Starts scheduled jobs and catch-up jobs	The beat schedule in backend/app/worker/celery_app.py
Agent runtime	Agent list, planner, the workflow fixed for each run, saved progress, leases, tools and review	backend/app/agents/workflow.py, backend/app/services/agent_capability_registry.py
PostgreSQL	The main database, and the saved records of work in progress	backend/app/models/postgres.py
MongoDB	Detailed evidence, summaries, decision documents, and the raw and cleaned-up data that was sent	backend/app/db/mongo.py (the list of collections and indexes)
Redis	Job queue and results, live streams, sending updates to viewers, session buffers, usage limits and caches	backend/app/streams, backend/app/db/redis_client.py
File storage	Uploads waiting to be processed, files, exports, and training and knowledge files	backend/app/db/storage.py
AI model and search services	The local or cloud AI model you set up, and optional document search	backend/app/services/llm_factory.py, backend/app/services/semantic_search.py
Command-line tool, MCP server and SDKs	Use the API, and send test results to TestLookup	The integration map

Open the diagram full size

Steps in this diagram, as text

Producers: External test runners and CI, Browser or CLI report upload, Drop folder with a marker file

Application: FastAPI routes and auth, Domain services, Redis broker and live streams, General and ingestion workers, Isolated agent child workers, Beat and reconciliation, Agent workflow and policies

Persistence: PostgreSQL, MongoDB, MinIO S3 or local storage, Optional ChromaDB

• External test runners and CI → FastAPI routes and auth
• Browser or CLI report upload → FastAPI routes and auth
• Drop folder with a marker file → FastAPI routes and auth
• FastAPI routes and auth → Domain services
• FastAPI routes and auth → Redis broker and live streams
• Domain services → PostgreSQL
• Domain services → MinIO S3 or local storage
• Redis broker and live streams → General and ingestion workers
• Redis broker and live streams → Isolated agent child workers
• Beat and reconciliation → Redis broker and live streams
• General and ingestion workers → Domain services
• General and ingestion workers → Agent workflow and policies
• Isolated agent child workers → Agent workflow and policies
• Agent workflow and policies → PostgreSQL
• Agent workflow and policies → MongoDB
• Agent workflow and policies → Optional ChromaDB
• Agent workflow and policies → Policy-approved model provider
• Domain services → MongoDB
• FastAPI routes and auth → UI polling SSE and WebSocket

Before you change a feature that spans several of these parts, read the extension guide.