An operational layer for AI-assisted business workflows
A2B is a developing platform for creating, reviewing, and monitoring business workflows across departments. Its local MVP includes department and business-record CRUD, a React Flow editor, persisted workflows, opt-in live agent tasks, human approvals, version snapshots, workspace administration and audit history.
System architecture
| Layer | Technology | Current responsibility |
|---|---|---|
| Web application | Next.js + TypeScript | Business workspaces, forms, routing, dashboards |
| Workflow canvas | React Flow | Node editing, connections, branches, properties |
| API | Python FastAPI | Workflows, records, approvals, runs, audit endpoints |
| Persistence | SQLite (development) | Sample data, workflow versions, audit and traces |
| Execution | Python worker + model gateway | Simulations and explicit live agent runs, scoped reads, human-approved local drafts, persisted traces |
| Packaging | Docker Compose | Local frontend and backend development |
Conceptual business flow
Inbound enquiry
→ Qualify lead [simulated]
→ Qualified?
Yes → Quotation approval [human gate]
→ Draft invoice [simulated]
→ Record outcome
No → Marketing nurture [simulated]
→ Record planned follow-up
The full-stack application supports OIDC/PKCE, a bounded model/tool loop, a read-only HubSpot adapter, and an optional PostgreSQL 17 persistence backend with guarded offline SQLite import, bounded connection pools and native concurrent SKIP LOCKED queue claiming. Distributed high-throughput scheduling, managed migrations, database RLS, OAuth onboarding, external write adapters and measured ROI remain production work. The public demo never calls those services.
Run the full-stack application
Install Docker Desktop or Docker Engine with the Compose plugin, then run:
git clone https://github.com/savisaluwadana/A2B-Agentic-Business-OS.git cd A2B-Agentic-Business-OS docker compose up --build
Once the containers have started, open http://localhost:3000 for the Next.js application and http://localhost:8000/docs for the FastAPI OpenAPI interface.
Both local API and worker store development data in the same named Docker volume. Do not expose its port on a public interface or use it with real customer data. For direct development without Docker, see the repository's README.
Workflow Studio
The full-stack editor supports Trigger, Agent, Action, Condition, Human Approval, End, Parallel Split and Join nodes. Click + on any connection to insert a step without manually rewiring downstream connections. Parallel Split fans out to two to eight independently queued branches, and a paired Join can wait for ALL branches or continue after ANY first arrival. Approvals genuinely pause stored execution; explicit live runs execute enabled bound agents through the worker. External Action nodes remain simulation-only. A separate, approval-gated Action Outbox page can create durable, internal draft records with human review, idempotency keys and local-only retries. It does not send external requests.
Visual execution debugger
Open Workflows → Execution History → View execution diagram in the full-stack application to see the exact saved graph for that run. Nodes show queued, running, waiting, completed, cancelled or skipped states. Join details show arrivals and ALL/ANY synchronization, and the view refreshes while the run is active. Its read-only diagnostics exclude raw input, private agent prompts, knowledge content and model outputs. Run history inputs are collapsed by default. This debugger is a full-stack feature; the public browser-only HTML demo remains illustrative.
Execution Monitor and run recovery
The full-stack application includes a dedicated Execution Monitor page (`/runtime`). It shows worker heartbeat freshness, queued and expired jobs, pending approvals, failed and stalled runs, and deep links to saved execution diagrams. The worker writes a heartbeat approximately every 15 seconds, including during long model calls. With PostgreSQL enabled, workflow job and agent task claims are concurrent at the row level; subsequent state transitions and audit writes remain serialized. Warnings use visible thresholds, not fabricated uptime or ROI measurements. Only editor/admin users may cancel or retry eligible workflow runs. Retrying is restricted to failed sequential simulations; paid live calls or partially completed parallel workflows cannot be safely replayed.
Workflow versioning
Each save creates a numbered definition snapshot. Runs are pinned to the definition they started with so editing a workflow cannot change an already-paused execution. Concurrent edits are rejected using version preconditions. This is a development safeguard; it is not a durable distributed execution engine.
Approved local action outbox
The full-stack app includes an Action Outbox at /actions. Authorized editors can request an internal draft, a separate OIDC approver/admin can approve or reject it, and the worker commits the local draft and audit event together. PostgreSQL uses a versioned v4 tenant RLS table. Read the local-action contract. Messages, payments, arbitrary tools and CRM writes remain disabled.
Audit trail
Workflow changes, run transitions and approval decisions are recorded in a locally verifiable hash chain. An administrator controlling the SQLite file could rewrite the chain; production-grade audit requires external append-only storage and authenticated actors.
Department workflow templates
Use the Workflow Studio starter library to create an editable local copy of a business process. Templates are curated rather than automatically generated by an LLM, and do not enable real tool execution.
| Template | Department | What it demonstrates |
|---|---|---|
| Enquiry to revenue | Sales | Qualification, branching, quote approval, invoice draft |
| Marketing campaign review | Marketing | Campaign content, editorial approval, scheduling draft |
| Invoice review and payables | Finance | Invoice validation, finance sign-off, draft entry |
| New employee onboarding | HR | Checklist, HR review and task coordination |
| Procurement request | Operations | Request classification and manager review |
| Customer support escalation | Support | Ticket classification, escalation review and response draft |
Development API
Representative endpoints include:
GET /healthz
GET /v1/templates
POST /v1/templates/{id}/instantiate
GET /v1/workflows
GET /v1/workflows/{id}/versions
PUT /v1/workflows/{id} # If-Match: version
POST /v1/workflows/{id}/runs # optional Idempotency-Key
GET /v1/runs
GET /v1/runtime/overview # sanitized worker and queue health
GET /v1/runs/{id}/inspection # pinned read-only execution diagram
GET /v1/approvals
POST /v1/approvals/{id}/decision
GET /v1/audit
GET /v1/audit/verify
Default local demo mode recognizes only a fictional tenant. An optional OIDC-protected API and browser PKCE sign-in preview support provisioned organizations and roles. Production BFF sessions, real provider verification, and PostgreSQL tenancy controls are not implemented. Public visitors should use the static HTML demo, not the backend.
Create agents, workflows and integration configurations
The local development application now supports department-specific agent profiles with goals, instructions and integration assignments. Integration Hub stores provider configuration descriptors, scoped access intentions, and local-only checks. Workflow Studio supports an expanded graph canvas, fit and zoom controls, collapsible panels, and saved agent/integration references on nodes.
Live model calls require server configuration and a tenant allowlist. HubSpot contacts can be read using an operator-bound token; other provider entries remain descriptors. Financial posting and external messaging are unavailable. For developer instructions see Creator Studio guide.
Authenticated API preview
Developers can now opt into a fail-closed OIDC resource-server mode. The API verifies signed RS256 access tokens and organization memberships, enforcing separate viewer, editor, approver and administrator roles. Admins can provision and revoke memberships through protected endpoints after an offline first-admin bootstrap.
The Next.js web application now includes opt-in OIDC Authorization Code + PKCE sign-in and membership checks; however it is not a production BFF/session design. Real IdP end-to-end testing, PostgreSQL RLS, secure cookies and external write connectors remain outstanding. See API authentication and RBAC guide.
Department control centers
Marketing, Sales, Finance, People & HR, Operations and Customer Support now have dedicated tabs for Overview, Workflows, Agents, Context & Knowledge, Integrations and Records. The development application supports departmental workflow creation, deep-linked agent and integration configuration, and versioned knowledge, FAQ and playbook records that can be assigned to agent profiles.
The standalone HTML demo includes department panels with browser-local create, view, edit and delete controls (stored in localStorage until reset). No demo interaction runs an external service or AI model. See the department workspaces guide for setup, APIs and limitations.
Agentic MVP setup and management
Create custom teams in Departments. Each team can manage context, agent profiles, workflows, integration descriptors and records. Sales leads, campaign plans and draft invoices have complete content CRUD; reviewed records and execution history retain deletion guards. Settings stores workspace preferences, and Members manages OIDC roles and revocation.
The Agent execution page queues tasks, shows model/tool output and pinned source versions, and lets authorized reviewers approve or reject proposed local drafts. Live workflows pause at agent nodes and resume after task completion and any required approval.
A2B_LIVE_TENANTS=demo AI_GATEWAY_MODEL=openai/gpt-4.1-mini AI_GATEWAY_API_KEY=your-server-only-key
Configure these only on the API and worker, then recreate them. Never put keys in the browser. The default remains offline simulation. See the MVP guide for HubSpot token binding, API contracts, state transitions and troubleshooting, and the architecture for diagrams and production boundaries.
What is safe today?
Missing production controls
- Production BFF sessions, identity-provider acceptance tests and account recovery
- PostgreSQL with migrations, tenant isolation and encrypted secret storage
- Production-grade durable workers, replay-safe external actions and connector-level idempotency
- Credential-scoped business integrations and webhook signature verification
- Financial segregation of duties, controlled posting and independent audit storage
- Penetration testing, observability, error budgets, backups and incident response
How this GitHub Pages site works
The marketing site and HTML demo are stored under site/. A GitHub Actions workflow verifies the static files, uploads a Pages artifact, and deploys it from main when GitHub Pages is configured.
- In the repository, open Settings → Pages.
- Under Build and deployment, choose GitHub Actions.
- Merge the reviewed website pull request into
main; the deployment workflow runs for changes undersite/. - Find the published URL in the github-pages deployment or the workflow summary.
Important: The current repository is private. GitHub Pages for a private repository depends on the repository owner's GitHub plan and settings. The published Pages site is publicly visible even when the repository stays private. Only static public demo assets are deployed.
What's next
- Harden the existing OIDC/member authorization preview and migrate persistence to production PostgreSQL.
- Distributed execution, independent audit storage, operational monitoring and production recovery tests.
- WhatsApp, CRM, MCP, accounting and marketing integrations with approved scoped access.
- Production-ready sales and finance objects, reliable reconciliation and consent-aware marketing workflows.
- Business discovery recommendations, workflow test suites, measured ROI and paid onboarding.
View the current engineering backlog in the repository issues.