AI Agent Workflow Engine 🚀

A multi-tenant, enterprise-grade AI Agent Workflow Orchestration Engine built with Nhost (PostgreSQL, Hasura GraphQL Engine, Nhost Auth, Serverless Functions), Groq LLM API, and Next.js.

Designed for chaining autonomous AI agent steps, enforcing strict multi-tenant data boundaries, and applying a dual-layer role-based permission system with human-in-the-loop approval gates.

---

Demo Walkthrough

Link : https://drive.google.com/file/d/16WDUc1yO2vSmmU40a-hQEfkFtZA8RqCc/view?usp=sharing

---

🏛 System Architecture & Stack

Layer	Technology	Description
Frontend Framework	Next.js 16 (App Router, Turbopack)	Responsive, dark-themed UI built with React 19 and Tailwind CSS.
GraphQL & State Management	Apollo Client	Managed GraphQL queries, mutations, and real-time execution polling.
Backend & Database	Nhost + Hasura GraphQL Engine	Managed PostgreSQL database, GraphQL API generator, and RBAC matrix.
Serverless Functions	Node.js (TypeScript)	Custom Hasura Actions (/triggerWorkflowRun, /approveStep) & Event Triggers (/executeStep).
LLM Inference	Groq API (llama3-8b-8192)	Live, high-speed LLM execution for AI agent step nodes.
Deployment	Netlify + Nhost Cloud	CD deployment with automated migrations and metadata application.

---

🔒 Security Architecture: Dual-Layer Authorization

The platform strictly enforces two separate layers of security:

                  ┌──────────────────────────────────────────────┐
                  │              GraphQL Request                 │
                  └──────────────────────┬───────────────────────┘
                                         │
                                         ▼
                  ┌──────────────────────────────────────────────┐
                  │      Layer 1: Multi-Tenant Isolation         │
                  │   Checks: user_id = X-Hasura-User-Id         │
                  │   in tenant's org_members table              │
                  └──────────────────────┬───────────────────────┘
                                         │
                                         ▼
                  ┌──────────────────────────────────────────────┐
                  │     Layer 2: Step-Level Permission Gating    │
                  │   - DB Level: _nin [db_write, notify]        │
                  │   - Action Level: Role verification for      │
                  │     approval_gate steps                      │
                  └──────────────────────────────────────────────┘

1. Layer 1 — Multi-Tenant Data Isolation

• Prevents cross-tenant data leakage. Every Hasura query, insert, update, and delete is scoped to the caller's organization via an org_members join filter.
• Cross-Tenant Role Lock: To prevent a user who is an owner in Tenant A from elevating privileges in Tenant B where they are an editor, permissions explicitly evaluate the caller's role within the target organization's org_members record.

2. Layer 2 — Step-Level Gating & Privileged Actions

• Database Level Enforcement (_nin Constraints): Hasura metadata constraints restrict editor roles from creating or updating high-privilege steps (db_write, notify) or triggers (webhook). Only owner roles can access these resources.
• Action Handler Level Enforcement: Clearing an approval_gate step mid-execution is handled via the /approveStep serverless function. It verifies the approver's role in backend logic before resuming execution.
• Quota Safeguards: usage_quota on organizations is read-only for tenant owners, preventing unauthorized quota manipulation.

---

📊 Database Schema Model

The PostgreSQL database comprises 8 core entities:

• organizations: Tenant container with usage_quota and calls_used.
• org_members: Maps user_id to org_id with roles (owner, editor, viewer).
• workflows: Belongs to an organization.
• workflow_steps: Ordered execution steps (llm_call, http_request, db_write, notify, conditional_branch, approval_gate).
• workflow_triggers: Trigger configurations (manual, webhook, scheduled, database_event).
• workflow_runs: Tracks execution run instances and overall status (pending, running, completed, paused, failed).
• step_runs: Detailed per-step execution logs, inputs, outputs, errors, attempt counts, and approval audit metadata (approved_by, approved_at).
• org_usage_stats: A PostgreSQL view calculating remaining quota and execution metrics per tenant.

---

⚡ Execution Pipeline & Approval Lifecycle

1. Triggering a Run: The /triggerWorkflowRun Hasura Action validates tenant membership, verifies remaining_quota > 0, creates a workflow_run, and initializes step_runs.
2. Event-Driven LLM Execution: Inserting a step run fires a Hasura Event Trigger pointing to /executeStep. For llm_call steps, the function calls Groq's API and updates the output.
3. Approval Gate Pause: When an approval_gate step executes, the run pauses in running status.
4. Approval & Resume: An authorized user triggers the /approveStep Action. The handler verifies their role in org_members, records audit timestamps, marks the step completed, and signals execution to resume.

---

🛠 Local Setup & Development

1. Prerequisites

• Node.js >= 18.x
• npm / yarn / pnpm

2. Environment Setup

Create a .env.local file in the root directory:

NEXT_PUBLIC_NHOST_SUBDOMAIN=s******************p
NEXT_PUBLIC_NHOST_REGION=ap-south-1
NEXT_PUBLIC_NHOST_GRAPHQL_URL=https://s*****************p.hasura.ap-south-1.nhost.run/v1/graphql

Note: For backend serverless functions running on Nhost Cloud, set GROQ_API_KEY under Nhost Dashboard Settings -> Environment Variables.

3. Installation & Local Run

# Install dependencies with legacy peer deps option for React 19 compatibility
npm install --legacy-peer-deps

# Start Next.js development server
npm run dev

Visit http://localhost:3000 to access the application.

---

📄 Documentation Deliverable

For a comprehensive architectural breakdown on schema design reasoning, Hasura metadata configurations, and approval gate lifecycles, read ARCHITECTURE.md.