kanvas-ecosystem-api

Kanvas is the nervous system for modern operations.
It connects your systems, orchestrates workflows, and enables AI agents and humans to execute real operational work across your business.

Think of Kanvas as the layer where operations become executable.

Not a storefront.
Not just a CRM.
Not another automation tool.

Kanvas is the operational execution layer that unifies your stack and allows intelligence to act on it.

Why Kanvas Exists

Modern companies operate across fragmented systems:

• Shopify for commerce
• NetSuite for operations
• HubSpot for CRM
• Slack for communication
• Internal tools and spreadsheets everywhere
• AI tools disconnected from execution

Every company ends up rebuilding the same operational infrastructure: authentication, permissions, product synchronization, lead routing, workflow orchestration, integrations, event pipelines, operational APIs.

And even with AI, most systems still stop at conversation instead of execution.

Kanvas was built to solve that.

It provides a modular operational nervous system where APIs, workflows, events, and AI agents work together to run real operations.

What Kanvas Is

Kanvas is a Laravel + GraphQL operational backend designed to unify operational logic across systems.

It provides:

• Unified operational APIs
• Cross-system workflows
• Event-driven infrastructure
• Multi-tenant architecture
• Agent-ready execution primitives
• Operational memory and orchestration layers

So you can build systems where:

• Products sync automatically
• Inventory propagates across channels
• Leads route themselves
• Teams operate from unified data
• AI agents execute operational tasks
• Business logic lives in one place

The Nervous System Model

Without a nervous system, AI is just a chatbot.

Kanvas gives AI agents operational awareness and execution capabilities by connecting products, customers, inventory, CRMs, internal APIs, workflows, and operational events.

This allows agents to move from:

"Here's what you should do"

to:

"I've already done it."

Core Domains

Kanvas is composed of operational building blocks:

• Ecosystem – authentication, apps, teams, multi-tenancy
• Inventory – products, variants, channels, catalogs
• CRM – people, leads, pipelines, organizations
• Workflow – actions, automations, orchestration
• Commerce – orders, fulfillment, operational logic
• Social – messaging, feeds, interactions
• Agents – execution, orchestration, operational memory

You don’t install disconnected features.
You assemble an operational nervous system for your business.

What People Use Kanvas For

• 🚘 Dealer platforms (inventory + CRM + lead routing)
• 🛍 Marketplaces (products, vendors, fulfillment workflows)
• 🏪 B2B commerce systems (pricing, approvals, operations)
• 🧩 Product configurators and bundlers
• 📱 Headless commerce applications
• 🤖 AI agent infrastructure and execution systems
• 🧠 Internal operational platforms and AI desks

The Mental Model

Kanvas is not your app.

Kanvas is the operational layer your apps, agents, and teams run on.

Your frontends, dashboards, workflows, and AI agents connect to Kanvas — and Kanvas connects to the rest of your infrastructure.

UI / Mobile / Dashboards / AI Agents
                 ↓
             Kanvas
                 ↓
Shopify • NetSuite • CRMs • Internal APIs • Workflows

Prerequisites

• PHP ^8.5
• Laravel ^13.0

Initial Setup

1. Use the docker compose up --build -d to bring up the containers. Make sure to have Docker Desktop active and have no other containers running that may cause conflict with this project's containers(There may be conflicts port wise if more than one container uses the same ports).

2. Check the status of containers using the command docker-compose ps. Make sure they are running and services are healthy.

3. Get inside the database container using docker exec -it mysqlLaravel /bin/bash. Then, create 7 databases: inventory, social, crm, workflow, commerce, action_engine, event.

4. Set up your .env: You can start by copying the .env.example setup. Next, update it with the database and Redis connection info, making sure that the host values match your container's name.

5. Get inside the php container using docker exec -it phpLaravel bash.

6. Generate app keys with php artisan key:generate. Note: Confirm that your app key is correctly registered in the apps table within the kanvas_laravel database.

7. Update the app variables in your .env APP_JWT_TOKEN, APP_KEY, KANVAS_APP_ID before running the setup-ecosystem. Note: You can use the default values provided in tests.yml.

8. Use the command php artisan kanvas:setup-ecosystem to run the kanvas setup.

9. If you're presenting some errors after running the command from before, drop all the tables from the schema kanvas_laravel and run it again.

10. To check if the API is working just make a GET request to http://localhost:80/v1/ and see if the response returns "Woot Kanvas".

Setup Inventory

1. composer migrate-inventory
2. Set env var in .env

   DB_INVENTORY_HOST=mysqlLaravel
   DB_INVENTORY_PORT=3306
   DB_INVENTORY_DATABASE=inventory
   DB_INVENTORY_USERNAME=root
   DB_INVENTORY_PASSWORD=password

php artisan inventory:setup to create and initialize the inventory module for a current company

Setup Social

1. composer migrate-social
2. Set env var in .env

   DB_SOCIAL_HOST=mysqlLaravel
   DB_SOCIAL_PORT=3306
   DB_SOCIAL_DATABASE=social
   DB_SOCIAL_USERNAME=root
   DB_SOCIAL_PASSWORD=password

php artisan social:setup to create and initialize the social module for a current company

Setup Guild

1. composer migrate-crm
2. Set env var in .env

   DB_CRM_HOST=mysqlLaravel
   DB_CRM_PORT=3306
   DB_CRM_DATABASE=cr
   DB_CRM_USERNAME=root
   DB_CRM_PASSWORD=password

php artisan guild:setup to create and initialize the crm module for a current company

Running the project with Laravel Octane

After doing all the steps above, you could run the project with Laravel Octane by using the command php artisan octane:start --server=swoole --host=0.0.0.0 --port=8000.

Use --watch in development allowing you to refresh modified files, this works assuming to have npm install chokidar installed in the project.

Deployment to GCP with Ansible

This project uses GitHub Actions with Ansible to deploy to Google Cloud Platform (GCP) compute instances using Workload Identity Federation for secure authentication.

Architecture Overview

• GitHub Actions: Orchestrates the deployment workflow
• Workload Identity Federation: Secure authentication to GCP without storing service account keys
• Ansible: Automates deployment tasks across GCP compute instances
• Dynamic Inventory: Automatically discovers GCP instances based on naming patterns

GCP Setup

1. Create Workload Identity Pool

export PROJECT_ID="your-project-id"
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export REPO="bakaphp/kanvas-ecosystem-api"

# Create Workload Identity Pool
gcloud iam workload-identity-pools create "github-pool" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --display-name="GitHub Actions Pool"

2. Create OIDC Provider

gcloud iam workload-identity-pools providers create-oidc "github-provider" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --workload-identity-pool="github-pool" \
  --display-name="GitHub Actions Provider" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --attribute-condition="assertion.repository_owner=='bakaphp'"

3. Create Service Account

# Create service account
gcloud iam service-accounts create github-actions-sa \
  --project="${PROJECT_ID}" \
  --display-name="GitHub Actions Service Account"

export SA_EMAIL="github-actions-sa@${PROJECT_ID}.iam.gserviceaccount.com"

# Grant necessary permissions
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/compute.viewer"

# Grant OS Login permissions for SSH access (replaces SSH keys)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/compute.osAdminLogin"

# Allow Workload Identity to impersonate the service account
gcloud iam service-accounts add-iam-policy-binding "${SA_EMAIL}" \
  --project="${PROJECT_ID}" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/github-pool/attribute.repository/${REPO}"

4. Get Provider Path

# Get the full provider path for GitHub secrets
gcloud iam workload-identity-pools providers describe github-provider \
  --workload-identity-pool=github-pool \
  --location=global \
  --project=$PROJECT_ID \
  --format="value(name)"

5. Enable OS Login (Replaces SSH Key Management)

OS Login uses IAM for SSH authentication, eliminating the need to manage SSH keys. This is more secure and provides automatic key rotation.

# Enable OS Login at project level (applies to all instances)
gcloud compute project-info add-metadata \
  --metadata enable-oslogin=TRUE \
  --project=$PROJECT_ID

# Verify OS Login is enabled
gcloud compute project-info describe \
  --project=$PROJECT_ID \
  --format="value(commonInstanceMetadata.items.filter(key:enable-oslogin))"

Benefits of OS Login:

• No SSH keys to store in GitHub Secrets
• Automatic credential rotation via IAM
• Centralized access control
• Full audit logging via Cloud Audit Logs
• Works seamlessly with Workload Identity Federation

For Managed Instance Groups: OS Login is automatically applied to all current and future instances when enabled at the project level. No changes to instance templates required.

GitHub Configuration

Required Secrets

Go to: Repository Settings → Secrets and variables → Actions → New repository secret

Required Variables

Go to: Repository Settings → Secrets and variables → Actions → Variables

GitHub Environments

Create environments matching your branch names (e.g., development, staging, main) in: Repository Settings → Environments

This allows branch-specific configurations and deployment protection rules.

Deployment Workflow

The deployment is triggered manually via workflow_dispatch. To deploy:

1. Go to Actions tab in GitHub
2. Select "Ansible GCP Compute Deploy" workflow
3. Click "Run workflow"
4. Select the branch to deploy
5. Click "Run workflow"

What Happens During Deployment

1. Authentication: Authenticates to GCP using Workload Identity Federation
2. Dynamic Inventory: Discovers running GCP instances in the specified region matching the instance group name
3. File Sync: Syncs application files to remote servers (excluding git, node_modules, vendor, etc.)
4. Dependencies: Installs Composer dependencies
5. Migrations (optional): Runs database migrations
6. Cache: Clears and rebuilds Laravel config/route/view cache
7. Docker: Restarts Docker containers with updated code

Ansible Playbooks

Playbooks are organized by environment in ansible/playbooks/:

• development-deploy.yaml
• staging-deploy.yaml (if applicable)
• production-deploy.yaml (if applicable)

Playbook Structure

---
- name: Deploy app to all instances
  hosts: development  # Matches the group created by dynamic inventory
  become: true
  strategy: free  # Run on all hosts in parallel

  tasks:
    - name: Sync app files
      ansible.posix.synchronize: ...

    - name: Install dependencies
      command: composer install ...

    - name: Redeploy docker containers
      docker_compose: ...

GCP Instance Requirements

Instances must:

• Be named with the pattern matching INSTANCE_GROUP_NAME (e.g., development-api-01)
• Be in RUNNING state
• Have SSH access configured with the provided private key
• Have Docker and Docker Compose installed
• Have the application directory structure in place

Troubleshooting

Authentication Errors

Error: invalid_target

Solution: Verify the Workload Identity Provider path and ensure pool/provider are ACTIVE:

gcloud iam workload-identity-pools describe github-pool \
  --location=global \
  --project=YOUR_PROJECT_ID \
  --format="value(state)"

gcloud iam workload-identity-pools providers describe github-provider \
  --workload-identity-pool=github-pool \
  --location=global \
  --project=YOUR_PROJECT_ID \
  --format="value(state)"

Both should return ACTIVE.

No Hosts Found

Solution: Check that:

• Instances are running
• Instance names contain the INSTANCE_GROUP_NAME value
• Instances are in the specified GCP_REGION

gcloud compute instances list \
  --project=YOUR_PROJECT_ID \
  --filter="name~INSTANCE_GROUP_NAME AND status=RUNNING"

SSH Connection Issues

Solution: Verify SSH key is correct and user has access:

# Test SSH connection manually
ssh -i path/to/private-key username@instance-ip

Local Testing

Test the Ansible playbook locally:

cd ansible

# Test inventory discovery
ansible-inventory -i inventory.gcp.yml --list

# Run playbook with dry-run
ansible-playbook playbooks/development-deploy.yaml \
  -i inventory.gcp.yml \
  --check \
  --diff

Working with kanvas

• Coding guideline
• Wiki
• TypeScript SDK
• Documentation

Note:

• To install Swoole you can use the command pecl install swoole
• For production remove --watch from the command.
• roles_kanvas_legacy will be deleted in the future