CloudMind

Overview

CloudMind is a BYOC (Bring Your Own Cloud) knowledge system for the AI era. It helps you save URLs, notes, PDFs, browser captures, and AI-originated content into your own Cloudflare account, then turns them into structured assets that can be searched, cited, reprocessed, and used by AI clients.

The current project is a single HonoX full-stack application with a Web UI, REST API, queue-driven processing workflows, and a stateless remote MCP server. It uses Cloudflare D1, R2, Vectorize, Queues, and Workers AI by default while keeping the core domain behind replaceable ports.

Features

Why CloudMind

Architecture

graph TD
    Browser["Web UI"] --> HonoX["HonoX + Hono App"]
    API["REST API"] --> HonoX
    MCP["AI Clients / MCP"] --> HonoX
    HonoX --> Auth["Auth + MCP Tokens"]
    HonoX --> Assets["Asset Services"]
    HonoX --> Search["Search + Chat Services"]
    Assets --> Workflows["Workflow Runtime"]
    Workflows --> Queue["Cloudflare Queues"]
    Workflows --> AI["Workers AI"]
    Workflows --> Blob["R2 BlobStore"]
    Workflows --> Vector["Vectorize VectorStore"]
    Assets --> DB[("D1 + Drizzle")]
    Search --> DB
    Search --> Vector
    Queue --> Workflows

CloudMind keeps product logic separated from infrastructure details:

This shape supports the current Cloudflare-native MVP and leaves room for future PostgreSQL + pgvector, S3-compatible storage, and multi-provider AI.

Processing Model

Assets move through type-specific workflows:

• note_ingest_v1
• url_ingest_v1
• pdf_ingest_v1

Typical workflow:

1. Create asset metadata.
2. Persist raw input.
3. Create a workflow run.
4. Normalize and persist clean content.
5. Generate summary and metadata terms.
6. Split content into chunks.
7. Create embeddings.
8. Write vectors and chunk metadata.
9. Finalize asset status.

Queue consumption is wired in app/server.ts, and workflow dispatch is registered in src/features/workflows/server/registry.ts.

Quick Start

git clone https://github.com/evepupil/CloudMind.git
cd CloudMind
npm install
npm run dev

The Vite development server starts at:

http://localhost:5173

For a Cloudflare Worker-like local runtime, use:

npm run worker:dev

Environment And Bindings

CloudMind reads Cloudflare bindings from wrangler.jsonc. The application expects:

Binding types live in src/env.ts.

Deployment

Option A: Cloudflare Deploy Button

Use the deploy button at the top of this README, or open:

https://deploy.workers.cloudflare.com/?url=https://github.com/evepupil/CloudMind

Cloudflare guides repository connection, resource provisioning, and deployment.

Option B: One-Command Bootstrap

For a fresh Cloudflare account:

npm install
npm run deploy:one-click -- --prefix my-cloudmind

The script will:

• create D1, R2, Vectorize, and Queue resources
• update wrangler.jsonc bindings
• apply D1 migrations from drizzle/
• run the standard deployment pipeline

Bootstrap resources without deploying:

npm run deploy:bootstrap -- --prefix my-cloudmind

Option C: Standard Wrangler Deploy

npm run build
npm run db:migrate:remote
npm run deploy

Web Routes

API Surface

Ingest

• POST /api/ingest/text
• POST /api/ingest/url
• POST /api/ingest/file
• POST /api/assets/:id/process
• POST /api/assets/backfill/chunks

Assets

• GET /api/assets
• GET /api/assets/:id
• PATCH /api/assets/:id
• DELETE /api/assets/:id
• POST /api/assets/:id/restore
• GET /api/assets/:id/jobs
• GET /api/assets/:id/workflows

Workflows, Search, Chat, Health

• GET /api/workflows/:id
• POST /api/search
• POST /api/chat
• GET /api/health

MCP Server

CloudMind exposes a stateless HTTP MCP server at:

POST /mcp

Requests require a bearer token created from the /mcp-tokens page. GET /mcp and DELETE /mcp return 405 Method not allowed.

Available MCP tools:

Tool registration lives in src/features/mcp/server/service.ts, and routing lives in src/features/mcp/server/routes.ts.

Example Requests

Create a text asset:

curl -X POST http://localhost:5173/api/ingest/text \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cloudflare Queues notes",
    "content": "Queues drive async workflow execution in CloudMind."
  }'

Run semantic search:

curl -X POST http://localhost:5173/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "queue-driven ingestion",
    "page": 1,
    "pageSize": 10
  }'

Ask the memory layer:

curl -X POST http://localhost:5173/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How does CloudMind process ingested content?",
    "topK": 5
  }'

Project Structure

app/
  routes/                         HonoX pages
  server.ts                       app entry and queue consumer
src/
  core/                           domain ports and contracts
  env.ts                          Cloudflare binding types
  features/
    assets/                       asset queries, editing, soft delete, restore
    auth/                         login, password, session middleware
    capture/                      ingest UI
    chat/                         grounded Q&A
    health/                       health endpoint
    ingest/                       ingest services, PDF extraction, AI enrichment
    layout/                       app shell components
    mcp/                          remote MCP server
    mcp-tokens/                   MCP token management
    search/                       retrieval, evidence, term search
    workflows/                    workflow runtime and definitions
  platform/
    ai/                           Workers AI adapter
    blob/                         R2 adapter
    db/                           D1 schema and repositories
    observability/                structured logger
    queue/                        Cloudflare Queue adapter
    vector/                       Vectorize adapter
    web/                          URL extraction adapters
drizzle/                          D1 migrations
docs/                             design notes and product direction
tests/unit/                       Vitest unit tests

Scripts

npm run dev                 # Vite development server
npm run build               # Tailwind CSS build + Vite production build
npm run preview             # Preview production build
npm run worker:dev          # Wrangler local development
npm run worker:deploy       # Alias for deploy
npm run deploy              # Build, migrate remote D1, deploy Worker
npm run deploy:bootstrap    # Create Cloudflare resources and apply migrations
npm run deploy:one-click    # Bootstrap resources and deploy
npm run db:generate         # Generate Drizzle migrations
npm run db:migrate:remote   # Apply D1 migrations remotely
npm run typecheck           # TypeScript strict check
npm run lint                # Biome check
npm run format              # Biome format
npm run test                # Vitest unit tests

Testing

The repository includes unit coverage for:

• ingest services, routes, content processing, and PDF extraction
• asset services and routes
• search services, routes, evidence, and term expansion
• chat services and routes
• MCP routes and tool-facing behavior
• workflow services and components
• D1 repositories
• Workers AI provider
• observability logger

Recommended verification before a pull request:

npm run typecheck
npm run lint
npm run test

Design Principles

• Keep raw assets durable; derived AI output can be recomputed.
• Keep business logic behind ports instead of scattering D1, R2, Vectorize, or Workers AI details across features.
• Prefer queue-driven workflows for expensive processing.
• Validate external input with Zod at API and tool boundaries.
• Treat AI output as retryable, replaceable, and source-aware.
• Let retrieval degrade gracefully when some derived artifacts are missing.
• Keep feature code under src/features/<feature> and infrastructure adapters under src/platform.

Roadmap

Contributing

• Put new product modules under src/features/<name>.
• Keep infrastructure-specific code under src/platform.
• Use strict TypeScript and avoid any.
• Add focused tests when behavior crosses service, repository, API, or MCP boundaries.
• Run npm run typecheck, npm run lint, and npm run test before opening a pull request.

For deeper product and architecture constraints, see AGENTS.md.