Conversion Chatbot Framework (Project 9)

Demo Video

Release page: v1.0.0-final-submission

Alternative: YouTube (5:09)

A conversion focused chatbot framework with personality aware conversations, hybrid memory, SSE streaming, and engagement tracking.

Project requirements

See the original scope and deliverables: Project-Overview.md

Quick start (local)

### Prerequisites
- Docker Desktop running
- Node.js ≥20.0.0
- OpenAI API key

# clone
git clone https://github.com/HYGO-Labs/09-chatbot-framework-AlexSeisler

cd 09-chatbot-framework-AlexSeisler

# configure OpenAI API key
# Edit .env.example and replace the placeholder OPENAI_API_KEY with your key

# initial setup (db + env)
npm run setup

Note: First `npm install` takes 12-15 minutes due to large native binary downloads (Prisma, Next.js, Tailwind). Subsequent installs with cache are ~2-3 minutes.

# dev (api + web)
npm run dev

URLs (Local Development)

• Web: http://localhost:3000
• API: http://localhost:3001/api/v1
• Swagger: http://localhost:3001/api/docs

Production Deployment

• Frontend: https://chatbot-framework-deploy-web.vercel.app
• API: Render web service URL + /api/v1 (set via NEXT_PUBLIC_API_URL)
• Swagger: Render web service URL + /api/docs

---

What's implemented

• Personality system with admin-guarded CRUD
• Sessions and messages with atomic sequencing
• SSE streaming endpoint with token/complete/error/heartbeat events
• Hybrid memory: buffer + summaries + semantic search + pinned facts
• Engagement metrics and stage tracking
• Admin analytics and memory/session tooling

System overview (high level)

flowchart TB
    subgraph "Client Layer"
        User[User]
        Browser[Browser<br/>localhost:3000]
    end

    subgraph "Application Layer"
        WebApp[Next.js 14 Frontend<br/>apps/web<br/>Port 3000]
        API[NestJS Backend<br/>apps/api<br/>Port 3001]
    end

    subgraph "Data Layer"
        Prisma[Prisma ORM<br/>packages/database]
        PostgreSQL[(PostgreSQL<br/>Port 5432/5433)]
    end

    subgraph "Core Modules"
        Memory[Memory System<br/>Buffer + Summary + Semantic + Facts]
        Engagement[Engagement Tracking<br/>Stages: NEW -> LOYAL]
        Personality[Personality Engine]
        Chat[Chat Module<br/>Sessions + Messages]
    end

    subgraph "Shared"
        Types[Shared Types<br/>packages/types]
    end

    User --> Browser
    Browser -->|SSE Chat UI| WebApp
    WebApp -->|HTTP/SSE| API
    API --> Prisma
    Prisma --> PostgreSQL

    API --> Memory
    API --> Engagement
    API --> Personality
    API --> Chat

    Memory --> Prisma
    Engagement --> Prisma
    Personality --> Prisma
    Chat --> Prisma

    WebApp --> Types
    API --> Types

    style WebApp fill:#0070f3,color:#fff
    style API fill:#e0234e,color:#fff
    style Prisma fill:#2d3748,color:#fff
    style PostgreSQL fill:#336791,color:#fff
    style Memory fill:#10b981,color:#fff
    style Engagement fill:#10b981,color:#fff
    style Personality fill:#10b981,color:#fff
    style Chat fill:#10b981,color:#fff

Loading

---

Documentation map

Start here, then follow deeper docs as needed.

Core

• Final Architecture Decision
• API Overview
• SSE Events
• OpenAPI Specification

Database

• Overview
• ERD Implementation
• Schema Specification
• Prisma Schema

Packages

• API
• Database
• Web

Demo

• Conversations
• Video (local file)

Architecture Diagrams

• Component Architecture
• Memory Architecture
• End-to-End Flow (BPMN)

Daily Tracking Logs

• Daily Updates + Decisions
• Daily Development + Tradeoffs

Testing

API: Comprehensive unit test suite with 96%+ coverage across services, guards, and business logic.

Web: Component testing in progress (foundation established, expanding coverage incrementally).

Database: 12 tests passing (model validation, index performance). No coverage tracking - package is a thin Prisma client wrapper.

Run tests:

# API unit tests
npm run test --workspace @project-9/api

# API integration tests (requires test DB + server)
# Set test database environment(prevents prod DB conflicts)
$env:DATABASE_TEST_URL="postgresql://chatbot:test@localhost:5433/chatbot_test?schema=public"
$env:DATABASE_URL=$env:DATABASE_TEST_URL

npm run test:integration --workspace @project-9/api

# Database tests
npm run test --workspace @project-9/database

# Coverage report (API only)
npm run test:coverage --workspace @project-9/api


Web: Component testing in progress (foundation established, expanding coverage incrementally).

npm run test --workspace @chatbot/web

OpenAPI generation (source of truth)

OpenAPI is generated from NestJS decorators.

npm run openapi:generate
npm run openapi:validate

Monorepo structure

apps/
  api/     # NestJS backend
  web/     # Next.js frontend
packages/
  database/ # Prisma schema + migrations
  types/    # Shared types
scripts/    # setup/dev automation

Tech stack

• Backend: NestJS 11, TypeScript
• Frontend: Next.js 14
• Database: PostgreSQL 15, Prisma, pgvector
• Streaming: SSE
• Testing: Vitest, supertest, Playwright

CI/CD

Status: Production pipelines active

Automated Deployments:

• Backend: Render (triggers on main push)
• Frontend: Vercel (triggers on main push)
• Database: Prisma migrations auto-applied

Testing:

• Local execution pre-commit (unit, integration, E2E)
• CI configuration ready for production workflow

Infrastructure:

• Docker containerization for dev/prod consistency
• Environment-based configuration
• Automated OpenAPI spec generation

---

Last updated: 02/05/2026