potpie - Moses Yebei

The Problem

Large monolithic codebases are hard to navigate, test, and evolve. Teams waste time locating definitions, understanding cross‑module effects, and keeping the knowledge graph of the system up‑to‑date. Without a disciplined architecture the blast radius of a change can be unpredictable, leading to fragile deployments.

What This Does

potpie bundles a spec‑driven development platform that builds a knowledge graph of every file, class, and function. The core FastAPI service lives in app/, while the Rust‑based parser (app/src/parsing/) extracts structural metadata. Helper scripts (scripts/) and a seed CLI (seed/) bootstrap and manage projects.

Key files:

app/main.py – FastAPI entry point, creates the app, registers routes, and starts the lifespan event.
app/modules/utils/logger.py – the most‑imported hub (164 inbound imports).
app/modules/intelligence/provider/provider_service.py – high‑impact service (41 inbound imports, part of an import cycle).
app/src/parsing/src/lib.rs – Rust parser compiled via Cargo.toml.

The Dockerfile and docker-compose.yml (under deployment/) ship the whole stack, including Postgres, Neo4j, and Redis, so the system can be run locally with a single command.

How It Is Wired

Execution starts at app/main.py:274 in the run function. run traverses ~399 functions, ultimately invoking:

Database – get_project_repo_details_from_db → self.db.query(Project) (see app/core/database.py).
Network – run_pytest (via subprocess.run) and numerous outbound calls from app/api/router.py (e.g., create_conversation).
File system / Crypto – app/modules/repo_manager/repo_manager.py validates repo names, sanitises errors, and generates secrets via secrets.choice.

The most‑used internal symbols are query (called from 159 places) and getenv (99 places). The hub logger (app/modules/utils/logger.py) has zero outgoing imports, making it a stable anchor; any change here ripples to 164 modules.

Import cycles involve provider_service.py, code_provider_service.py, and tunnel_utils.py. These cycles increase cognitive load and risk of circular import errors; breaking them by extracting shared types or deferring imports would reduce instability (currently 0.56 for tool_service).

The call graph shows that UserLocalTunnelProvider is referenced from 59 locations, highlighting it as another high‑impact component.

External effects:

191 functions read/write the database.
141 functions perform outbound HTTP calls (e.g., to OpenAI, Neo4j).
22 functions generate cryptographic material.

How To Use It

# Clone with submodules
git clone --recurse-submodules https://github.com/moses-y/potpie
cd potpie

# Install UV (Python package manager) and sync deps
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Copy environment template and set required vars
cp .env.template .env
# Edit .env to provide:
#   LLM_PROVIDER, OPENAI_API_KEY, POSTGRES_SERVER, NEO4J_URI, REDISHOST, etc.

# Build and start all services (Docker, DB migrations, FastAPI, Celery)
chmod +x scripts/start.sh
./scripts/start.sh

The API is reachable at http://localhost:8001. Health can be verified with:

curl http://localhost:8001/health

To stop everything:

./scripts/stop.sh

Real‑World Use

A development team can point potpie at a new microservice repository. The parser (lib.rs) generates a graph that powers an AI assistant capable of answering “Which function updates the User table?” or “What code paths are affected by changing logger.py?”. The assistant queries Neo4j (via app/core/database.py) and returns precise, context‑aware suggestions, reducing onboarding time.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to commit SHA (.github/workflows/*).
HIGH – Replace wildcard CORS origin with an explicit allow list (app/main.py).
HIGH – CI does not run the test suite (.github/workflows/*).
MEDIUM – No least‑privilege GITHUB_TOKEN permissions (.github/workflows/test.yml).
MEDIUM – Dependabot / Renovate not configured (4 manifests present).
MEDIUM – No dependency‑vulnerability scan in CI (.github/workflows/*).
LOW – Workflow jobs lack timeout-minutes (.github/workflows/test.yml).

Static analysis also flagged:

Hub module (logger.py) – 164 dependents, keep stable.
Deep nesting (max depth 10) in several services – flatten for readability.
Oversized files (>1 200 lines) – split into cohesive units.
Broad exception handling – replace bare except with specific catches.
Import cycles – break by extracting shared types or inverting dependencies.

Dependencies: 103 packages, with 14 behind the latest major version (e.g., cryptography ≥ 46.0.7 vs 50.0.0).

The Bottom Line

potpie provides a concrete pipeline for turning a codebase into an actionable knowledge graph, backed by a FastAPI service and a Rust parser. The architecture is functional but suffers from several high‑impact health issues (unlocked CORS, missing test execution, import cycles) that should be addressed before production use. Teams comfortable fixing these concerns will gain a powerful, query‑able view of their code.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

616 files

Python500
Markdown13
Shell10
YAML8
Docker6
JSON5

FlaskDockerVector storeNeo4j

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["app 367 modules"] g1["tests 78 modules"] g2["potpie 30 modules"] g3["seed 15 modules"] g4["scripts 10 modules"] g1 -->|102| g0 g2 -->|41| g0 g3 -->|21| g0 g1 -->|4| g3 g4 -->|2| g0

Module dependencies

The 10 most depended-upon modules of 500, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_app_modules_utils_logger["logger"] n1_ce_provider_provider_service["provider_service"] n2_app_core_database["database"] n3_app_core_config_provider["config_provider"] n4_es_projects_projects_service["projects_service"] n5_telligence_agents_chat_agent["chat_agent"] n6_elligence_tools_tool_service["tool_service"] n7_ules_projects_projects_model["projects_model"] n8_versation_conversation_model["conversation_model"] n9_pp_modules_auth_auth_service["auth_service"] n1_ce_provider_provider_service --> n3_app_core_config_provider n1_ce_provider_provider_service --> n0_app_modules_utils_logger n6_elligence_tools_tool_service --> n0_app_modules_utils_logger n6_elligence_tools_tool_service --> n1_ce_provider_provider_service n7_ules_projects_projects_model --> n2_app_core_database n7_ules_projects_projects_model --> n8_versation_conversation_model n4_es_projects_projects_service --> n7_ules_projects_projects_model n4_es_projects_projects_service --> n0_app_modules_utils_logger classDef cyc stroke:#ef4444,stroke-width:2px; class n1_ce_provider_provider_service cyc;

Dependencies

14 of 103 declared dependencies are a major version behind. Resolved 75 of 103 against the registry.

Package	Declared	Latest	Behind
`cryptography`	>=46.0.7	50.0.0	4 major
`gunicorn`	>=23.0.0	26.0.0	3 major
`chardet`	>=5.2.0	7.6.0	2 major
`newrelic`	>=11.2.0	13.5.0	2 major
`tree-sitter-language-pack`	>=0.13.0	1.14.3	1 major
`logfire`	>=3.2.0	4.40.0	1 major
`neo4j`	>=5.28.2	6.2.0	1 major
`openai`	>=2.7.1	3.1.0	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium3

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

astral-sh/setup-uv@v4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh4 occurrences

pyo3@0.28.2 GHSA-36hh-v3qg-5jq4 (high) +3 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Replace the wildcard CORS origin with an explicit allow listhigh

app/main.py

cors() together with credentials enabled

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Make CI invoke the test suite it hashigh81 occurrences

.github/workflows

81 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/test.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set timeout-minutes on the workflow jobslow

.github/workflows/test.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.