Developers

Architecture and repository map

Understand the execution engine, SaaS control plane, data stores, and integration boundaries.

Last updated August 8, 2026

ScrumPulse is a Python automation engine plus a separate web control plane.

Runtime architecture#

Clerk user
    |
    v
Next.js dashboard  ---- bearer token ---->  FastAPI auth + RBAC  ----> SQL database
                                                   |
                                                   +----> Taiga or Jira API
                                                   +----> Stripe
                                                   +----> OpenAI / Upstash (optional chat)

External scheduler ---- environment secrets ----> Python execution engine
                                                        |
                                                        +----> Taiga or Jira
                                                        +----> Mattermost / Slack / Teams / SMTP
                                                        +----> audit and state files

Repository map#

Path	Responsibility
`execution/`	Board adapters, scrum cycles, safety gates, notifications, replanning, state, and CLI entry points.
`dashboard/api/`	FastAPI routes, auth, RBAC, models, encryption, approvals, exports, migration helpers, and tests.
`dashboard/web/`	Next.js App Router dashboard, public site, authentication UI, and documentation.
`api/index.py`	Python entry point used by the current Vercel API deployment path.
`alembic/`	Database migration environment and revision scripts.
`integrations/n8n/`	Importable n8n workflow artifact for the replanner approval loop.
`.github/workflows/`	Engine schedule, cleanup, and end-to-end test workflows.
`scripts/`	Local launch, scheduler, deployment, diagnostics, and cleanup helpers.
`deploy/`	Railway environment examples and systemd units.
`docs/deployment/`	Deployment readiness and provider setup notes.
`content/docs/`	Public documentation articles rendered by the Next.js portal.

Two credential paths#

The scheduled engine and dashboard do not share board credentials:

The standalone engine reads runtime environment variables or CI secrets.
The dashboard API reads an encrypted integration_settings row for the authenticated organization.

Do not assume that configuring one path configures the other.

Persistence#

The API supports SQLite for local development and PostgreSQL for production. SQLAlchemy models store organizations, subscriptions, integrations, runs, cycle statistics, actions, approval requests, and organization role assignments.

The engine also writes runtime state under tmp/, including project snapshots, audit output, proposal data, and local replanner checkpoints. Production deployments must decide which of those files need durable storage or database-backed replacements.

Scheduling#

GitHub Actions is the repository’s authoritative hosted scheduler. The API includes a lightweight in-process ticker, but skips it when VERCEL is present. Serverless deployments require an external scheduler.