AI-powered financial guardian that helps you pause before impulse purchases.

The average person makes multiple impulse purchases every week — and most regret them within days. Pause intercepts the moment of temptation with a three-tier AI system — analyzing risk, negotiating savings, and prompting reflection — so you make spending decisions you won't regret.

Built for the Encode Club Hackathon — Financial Health & Best Use of Opik categories.

Deep dives: Guardian AI | ACE Skillbooks | Opik Observability

• Architecture
• Features
• How It Works
• Tech Stack
• Prerequisites
• Quick Start
• Environment Variables
• Project Structure
• Scripts
• Deep Dive Articles
• Acknowledgements
• License

flowchart TB
    subgraph "apps/"
        WEB[web — Next.js 16 App]
    end

    subgraph "packages/"
        ACE[ace — Agentic Context Engine]
        API[api — tRPC Layer]
        AUTH[auth — Better Auth]
        DB[db — Drizzle + Neon]
        ENV[env — Zod Env Validation]
        CFG[config — Shared Config]
    end

    subgraph "external services"
        LLM[AI Provider — configurable]
        OPIK[Opik — Observability]
        NEON[Neon PostgreSQL]
    end

    WEB --> API
    WEB --> AUTH
    WEB --> DB
    WEB --> ACE
    WEB --> ENV
    WEB --> LLM
    WEB --> OPIK
    API --> AUTH
    API --> DB
    API --> ENV
    DB --> NEON
    AUTH --> DB
    AUTH --> ENV

• Guardian AI — Three-tier system (Analyst / Negotiator / Therapist) that adapts responses to purchase risk level
• Auto-approve — Low-risk purchases pass through instantly with no friction
• Coupon Search — Negotiator tier finds real savings and applies them before you unlock your card
• Reflection Prompts — Therapist tier guides you through evidence-based spending reflection techniques
• Floating Chat — Always-accessible AI assistant that answers questions about your spending and Pause features, with smart availability based on Guardian state

• ACE Learning — Self-improving Skillbook learns your spending patterns and gets smarter with every interaction
• Ghost of Spending Past — Resurfaces past purchases days later so you can reflect on whether they were worth it

• Dashboard — Interaction history, savings counter, and learning visualization
• Opik Observability — Full trace pipeline with reasoning summaries, strategy predictions, and feedback scores
• Demo Mode — Pre-seeded data and deterministic AI for live demonstrations (full judges' guide)

1. You tap your card to make a purchase
         ↓
2. Pause intercepts and assesses risk (low / medium / high)
         ↓
3. Low risk → Auto-approved instantly
   Medium risk → Negotiator finds coupons & savings
   High risk → Therapist prompts reflection
         ↓
4. You decide: unlock, save, or wait 24 hours
         ↓
5. Days later, Ghost Card asks: "Was it worth it?"
         ↓
6. Your feedback trains the AI — it learns YOUR patterns

• Node.js 20+
• Bun 1.x
• Neon PostgreSQL account (or local Postgres)
• AI provider API key (Google Gemini or Zhipu GLM-4.7-Flash)

# Clone
git clone https://github.com/armelhbobdad/pause.git
cd pause

# Install dependencies
bun install

# Set up environment
cp apps/web/.env.example apps/web/.env.local
# Edit .env.local with your credentials (see Environment Variables below)

# Push database schema
bun run db:push

# Start dev server (Turbopack)
bun dev

The app runs at http://localhost:3001.

pause/
├── apps/
│   └── web/                 # Next.js 16 application
├── packages/
│   ├── ace/                 # Agentic Context Engine (vendored fork)
│   ├── api/                 # tRPC router + procedures
│   ├── auth/                # Better Auth configuration
│   ├── config/              # Shared TypeScript config
│   ├── db/                  # Drizzle ORM schema + Neon client
│   └── env/                 # Zod-validated environment variables
├── scripts/                 # Seed scripts (seed-rookie, seed-pro)
├── turbo.json               # Turborepo pipeline config
└── package.json             # Workspace root

bun dev              # Start all apps in dev mode
bun build            # Production build
bun run check-types  # TypeScript type checking (all workspaces)
bun run db:push      # Push schema to database
bun run db:studio    # Open Drizzle Studio
bun test             # Run test suite

Technical deep dives exploring Pause's core systems:

• How Pause Turns Impulse Spending Into Smarter Decisions — Guardian state machine, tiered AI strategies, and the psychology behind the pause
• Self-Improving AI with ACE Skillbooks — How the ACE framework lets the Guardian learn and adapt its strategies over time
• Building Observable AI with Opik — End-to-end tracing and observability for AI interactions using Opik + Vercel AI SDK

• Encode Club — For launching and organizing this hackathon
• Better-T-Stack — For the strong project foundation
• Neon — For free-tier PostgreSQL credits
• Vercel — For free-tier hosting
• Zhipu AI — For free-tier GLM-4.7-Flash API access
• Google DeepMind — For free-tier Gemini 3 Flash Preview credits
• Opik — For free-tier observability platform credits
• Kayba AI — For the TypeScript port of the ACE framework

MIT — Armel BOBDA