The Problem

Operations teams need a way to own, audit, and modify AI‑driven workflows without relying on engineers to rewrite code. Existing agent implementations are buried in source files, lack visual oversight, and give no immutable execution log, making troubleshooting and compliance painful.

What This Does

EpicStaff delivers a self‑hosted visual editor that sits on a Django backend. The editor lives in frontend/ (React/Angular code, entry point frontend/public/epicchat-widget/main.js) and talks to the Python services in src/. Custom Python logic can be dropped into any node, while the platform records every decision in a PostgreSQL/Redis store. The repository is a portfolio of six independent projects, the largest being the core Django service (src/ ≈ 3 k files, 20 notebooks) and the web UI (frontend/ ≈ 1.6 k files). Integration tests (integration_tests/) and an installer (installer/) round out the distribution.

How It Is Wired

  1. Browser → Frontend entry – Loading frontend/public/epicchat-widget/main.js boots the SPA. The main bundle pulls in frontend/src/app/services/config/index.ts which reads runtime configuration (API base URL, feature flags).
  2. Frontend → API – HTTP calls are made from services in frontend/src/app/services/ (e.g., notifications, config) to Django REST endpoints defined under src/crew/ and src/shared/communication/.
  3. Django request handling – URLs in src/crew/urls.py route to view functions/classes that instantiate the agent engine (src/crew/agents/). The engine loads node definitions, executes custom Python snippets, and persists state via the ORM (PostgreSQL) and Redis caches.
  4. Agent → External resources – Nodes can invoke MCP connectors or arbitrary Python packages; the code for these adapters lives in src/crew/libraries/.
  5. Persistence & Auditing – Every step is written to the “session ledger” tables (src/crew/models/ledger.py) and optionally to a Redis stream for real‑time monitoring.
  6. Containerization – The whole stack can be built with frontend/Dockerfile.fe (frontend) and installer/Dockerfile.installer (backend). Docker Compose files (frontend/docker-compose.frontend.yml) orchestrate the services.

The most far‑reaching modules are the Django view layer (src/crew/views.py) and the agent execution core (src/crew/agents/engine.py); changes there affect every UI operation and all persisted runs.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/EpicStaff.git
cd EpicStaff

# Build containers (frontend and backend)
docker compose -f frontend/docker-compose.frontend.yml up --build -d

# Apply migrations (backend installer)
docker run --rm -v $(pwd)/installer:/app \
    -w /app python:3.11-slim \
    bash -c "pip install poetry && poetry install && poetry run python manage.py migrate"

# Start the Django dev server (if not using compose)
cd installer
poetry install
poetry run python manage.py runserver 0.0.0.0:8000

Configuration: API base URL is read from frontend/src/app/services/config/index.ts. Database credentials are expected in Django’s standard DATABASE_URL environment variable (refer to installer/pyproject.toml for required packages). No additional secret files are present besides the flagged src/crew/libraries/mem0/embedchain/.../.streamlit/secrets.toml, which should be removed or replaced with a secure vault reference.

Real‑World Use

A retail operations team deploys EpicStaff behind their internal VPN. A flow is built in the UI to monitor inventory levels, call an external ERP API via a custom Python node, and automatically create purchase orders. Every decision (e.g., “order 42 units”) is logged in the Django ledger, allowing auditors to trace the exact reasoning chain after the fact.

Code Health & Issues

Measured static‑analysis findings (11 total):

  • High – Pin GitHub Actions – .github/workflows/*.yml uses tag refs (@v3, @v6). Replace with 40‑char SHAs.
  • High – Upgrade vulnerable Angular deps – @angular/*@19.2.18 flagged (CVE‑2026‑54266, CVE‑2026‑32635). Upgrade to 22.x and update lockfile.
  • High – Missing lockfile – src/shared/communication/pyproject.toml lacks a poetry.lock. Run poetry lock and commit.
  • High – CI never runs tests – Workflows contain 592 test files but no test step. Add a pytest step.
  • Medium – Enable Dependabot – No dependabot.yml despite 111 manifest files.
  • Medium – Pin Docker base images – frontend/Dockerfile.fe uses mutable tags (node:20.17.0, nginx:alpine). Pin by digest.
  • Medium – Add vulnerability scan to CI – No dependency‑review or osv‑scanner step.
  • Medium – Large binary in repo – frontend/public/assets/ruff-wasm/ruff_wasm_bg.wasm (10 MB). Move to Git LFS or external storage.
  • Medium – Persist‑credentials false – .github/workflows/publish_release.yml keeps token after checkout. Set persist-credentials: false.
  • Medium – Run container as non‑root – frontend/Dockerfile.fe lacks a USER directive. Add an unprivileged user.

All findings are deterministic; fixes are described in the audit and should be applied before production use.

The Bottom Line

EpicStaff provides a functional visual AI‑workflow platform with a clear Django‑backed core and a modern TypeScript UI. The codebase is large and fragmented, with several high‑severity health issues that must be addressed—particularly dependency pinning, CI test execution, and container hardening. Teams comfortable managing Docker and Django can adopt it for internal agent orchestration, but they should first remediate the security findings and align the dependency versions.