Credo 🛍️

🏆 Built for the OWS Hackathon 2026 🏆

Credo is an AI-native commerce system that combines autonomous operations, a modern storefront, and verifiable trust rails.

It pairs a production-style Next.js frontend with a FastAPI backend, domain-specific agents, Supabase-backed persistence, and x402 machine-to-machine payment flows.

✨ At A Glance

• Autonomous Agents handle scouting, merchandising, logistics, and support.
• Production-Ready UI, including a storefront and admin surface designed for real operations, not just demos.
• Zero-Trust Rails using DIDKit and x402 add identity, verification, and automated escrow-style payments.
• Remotion Video Assets under video/ can be used for a narrated walkthrough or launch video.

🌊 App Flow

flowchart LR
    classDef trigger fill:#FEF9C3,stroke:#CA8A04,color:#854D0E,stroke-width:2px,rx:8px,ry:8px;
    classDef agent fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px,rx:8px,ry:8px;
    classDef proc fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:2px,rx:8px,ry:8px;
    classDef ui fill:#F3E8FF,stroke:#9333EA,color:#4C1D95,stroke-width:2px,rx:8px,ry:8px;

    A[⏱️ Scheduler]:::trigger --> B[🕵️ Scout Agent]:::agent
    B --> C{Margin & Trend pass?}:::proc
    C -- No --> D[Log rejection]:::proc
    C -- Yes --> E[Draft product]:::proc
    E --> F[✍️ Merch Agent]:::agent
    F --> G[Publish product]:::proc
    G --> H[🛍️ Storefront]:::ui
    H --> I[🛒 Customer orders]:::ui
    I --> J[📦 Logistics Agent]:::agent
    J --> K[🔐 Verify ID]:::proc
    K --> L[💸 Pay & Ship]:::proc
    L --> M[🎧 Admin & Support]:::ui

Loading

For the full journey map, see docs/app-flow.md.

🏗️ Architecture

flowchart TB
    classDef frontend fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px,rx:6px,ry:6px;
    classDef backend fill:#E0E7FF,stroke:#3B82F6,color:#1E3A8A,stroke-width:2px,rx:6px,ry:6px;
    classDef agent fill:#D1FAE5,stroke:#10B981,color:#064E3B,stroke-width:2px,rx:6px,ry:6px;
    classDef data fill:#FCE7F3,stroke:#EC4899,color:#831843,stroke-width:2px,rx:6px,ry:6px;
    classDef trust fill:#F5F3FF,stroke:#8B5CF6,color:#4C1D95,stroke-width:2px,rx:6px,ry:6px;
    classDef ops fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px,rx:6px,ry:6px;

    subgraph UI[🖥️ Customer and Admin UI]
        style UI fill:#FFF7ED,stroke:#FDBA74,stroke-dasharray: 5 5;
        storefront[Storefront]:::frontend
        admin[Admin Dashboard]:::frontend
        onboard[Supplier Onboarding]:::frontend
    end

    subgraph API[⚙️ Application Layer]
        style API fill:#EFF6FF,stroke:#BFDBFE,stroke-dasharray: 5 5;
        api[FastAPI Routers]:::backend
        auth[Auth & Rate Limits]:::backend
        support[Support API]:::backend
    end

    subgraph AGENTS[🤖 Autonomous Agents]
        style AGENTS fill:#ECFDF5,stroke:#A7F3D0,stroke-dasharray: 5 5;
        scout[Scout Agent]:::agent
        merch[Merchandiser Agent]:::agent
        logistics[Logistics Agent]:::agent
        supportAgent[Support Agent]:::agent
    end

    subgraph DATA[💾 Persistence & Trust Rails]
        style DATA fill:#FDF2F8,stroke:#FBCFE8,stroke-dasharray: 5 5;
        supabase[(Supabase SQL & Vector)]:::data
        store[(Local Store)]:::data
        payments[(x402 / Escrow)]:::trust
        didkit[(DIDKit / VC Verification)]:::trust
    end

    subgraph OPS[🛠️ Operational Control]
        style OPS fill:#FFFBEB,stroke:#FDE68A,stroke-dasharray: 5 5;
        scheduler[Scheduler]:::ops
        logs[Agent Logs]:::ops
        video[Remotion Assets]:::ops
    end

    scheduler --> scout
    scout --> supabase
    scout --> merch
    merch --> supabase
    storefront --> api
    admin --> api
    onboard --> api
    api --> auth
    api --> support
    support --> supportAgent
    api --> supabase
    supportAgent --> supabase
    logistics --> didkit
    logistics --> payments
    logistics --> supabase
    supabase --> store
    logs --> admin
    video --> storefront

Loading

📸 Screenshots

The repository includes real app screenshots used by the explainer video. They live under video/public/app/.

Home	Shop	Products

Track Order	Supplier Onboarding	Admin Dashboard

Admin Analytics	Admin Orders	Admin Products

📁 Project Structure

CredoCommerce/
├── backend/      FastAPI app, agents, services, migrations, tests
├── frontend/     Next.js app for consumer and admin experiences
├── video/        Remotion-based product and demo video pipeline
├── docs/         Product, architecture, and implementation docs
└── scripts/      Utility scripts

🚀 Tech Stack

• Frontend: Next.js, TypeScript, Tailwind CSS
• Backend: Python 3.12, FastAPI, Pydantic
• Data: Supabase for Postgres and vector-enabled workflows
• Identity & Payments: DIDKit and x402 integration paths
• Testing & Tooling: Playwright, pytest, ESLint

🛠️ Quick Start

1. Install dependencies

# Frontend
cd frontend && npm install

# Backend (recommended: virtual environment)
cd ../backend && pip install -r requirements.txt

2. Configure environment

cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env

3. Run services

# Option A: Docker
docker-compose up

# Option B: Local split
cd backend && PYTHONPATH=. python3 -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
cd frontend && npm run dev

💻 Common Commands

# Frontend build
cd frontend && npm run build

# Backend tests
cd backend && pytest

# Backend health check
curl http://127.0.0.1:8000/health

📚 Documentation

• Core product and architecture docs live in docs/.
• Deployment details are in DEPLOYMENT.md.
• x402 implementation notes are in docs/x402-implementation-summary.md.

🧹 Repository Hygiene

This repository uses a root gitignore tuned for monorepo workflows:

• Node and Python dependency directories
• Build and cache outputs
• Local environment and editor-specific files
• Generated media and temporary artifacts

⚖️ License

Private repository. All rights reserved unless otherwise specified.