VectorChat

VectorChat is an AI-powered agentic platform featuring retrieval-augmented generation (RAG), document ingestion, and agent tooling with skills management for advanced and scallable workflows.

This repo contains:

• cmd/ + internal/ + pkg/: Go API and workers
• frontend/: Nuxt 3 main UI
• vectorchat-light/: a lighter Nuxt UI
• ory/: Kratos/Hydra/Oathkeeper config
• services/: internal service containers (e.g., MarkItDown API, code runner)
• docker-compose.yml: full local stack

---

Quick start (Docker Compose)

Prereqs:

• Docker + Docker Compose
• LLM API keys (OpenAI/Gemini/etc.)

1. Create your env files:

cp .env.example .env
cp litellm/.env.example litellm/.env
cp vectorchat-light/.env.example vectorchat-light/.env

2. Fill in the required values in .env, litellm/.env, and vectorchat-light/.env.

3. Start the full stack:

docker compose up --build

4. Open the apps:

• Main UI: http://localhost:3000
• VectorChat Light: http://localhost:3100
• API gateway (Oathkeeper): http://localhost:4456
• Mailhog (dev email): http://localhost:8025
• pgAdmin: http://localhost:5050 (admin@example.com / admin)
• LiteLLM: http://localhost:4000

---

Configuration (.env)

Use .env.example as the source of truth. Common required values:

LLM

• OPENAI_API_KEY
• GEMINI_API_KEY (optional, for multi-provider setups)

OAuth (Ory Kratos/Hydra)

• GITHUB_ID
• GITHUB_SECRET

App URLs

• BASE_URL (Oathkeeper public base, default localhost:4456)
• FRONTEND_URL (default http://localhost:3000)
• IS_SSL (default false)

Database & migrations

• MIGRATIONS_PATH (default ./internal/db/migrations)

Optional integrations

• STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET
• GOOGLE_CALENDAR_CLIENT_ID, GOOGLE_CALENDAR_CLIENT_SECRET, GOOGLE_CALENDAR_REDIRECT_URL
• GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REDIRECT_URL
• SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_REDIRECT_URL
• ENCRYPTION_KEY (base64 32 bytes)

Additional env files:

• litellm/.env is used by LiteLLM for provider keys.
• vectorchat-light/.env configures the light UI client and OAuth credentials.

---

Services in the local stack

The Docker Compose stack includes:

• app: Go API server (Fiber) + core services
• frontend: Nuxt 3 main UI
• vectorchat-light: lightweight Nuxt UI
• postgres: PostgreSQL 14 + pgvector
• litellm: LLM proxy
• nats: JetStream queue
• oathkeeper, kratos, hydra: Ory auth stack
• crawl4ai, markitdown: web scraping + doc processing
• execute-code-worker: sandboxed code runner
• crawl-scheduler: background worker for crawl jobs
• mailhog: local SMTP inbox
• pgadmin: database UI

---

API reference & auth

API docs are served from the API root when the server is running:

• API docs: http://localhost:4456/ (Oathkeeper gateway)
• Aliases: /docs, /reference, /swagger
• OpenAPI: /openapi.json

Authentication flow (local):

1. Get a bearer token from POST /public/oauth/token through Oathkeeper
2. Click “Authorize” in the docs and paste Bearer <token>

---

Common commands

make build         # docker compose build
make run           # docker compose up -d
make stop          # docker compose down
make clean         # docker compose down -v
make migrate       # run goose migrations inside the app container
make swagger       # regenerate OpenAPI docs

---

Development notes

• The backend follows a layered architecture: Handler → Service → Repository.
• SQL lives in internal/db/ and uses sqlx.
• Auth is handled by Ory. Do not build custom auth flows.
• The Nuxt apps use useFetch and the Ory public URL for auth.

---

Troubleshooting

• Auth issues: ensure Ory containers are healthy and .env has GITHUB_ID/GITHUB_SECRET.
• LLM errors: check OPENAI_API_KEY in .env and litellm/.env.
• DB errors: verify Postgres is healthy and migrations ran (make migrate).

---

License

See LICENSE.