sercha-core

Table of Contents

1. About The Project
   • Features
   • Built With
2. Getting Started
   • Prerequisites
   • Quick Start
3. Architecture
4. Deployment Examples
5. Configuration
6. API Documentation
7. Development
8. Contributing
9. License

About The Project

Sercha Core is a self-hosted, team-wide search platform that connects your organization's data sources and provides unified search across all of them. Unlike the Sercha CLI which is designed for individual use, Sercha Core is built for teams with shared data, OAuth authentication, and horizontal scaling.

Why Sercha Core?

• Self-Hosted: Your data stays on your infrastructure - full control and privacy
• Team-Oriented: Shared sources, team management, and role-based access
• 11+ Connectors: GitHub, GitLab, Slack, Notion, Confluence, Jira, Google Drive, and more
• Hybrid Search: Semantic search powered by Vespa with optional AI enhancements
• Admin UI Included: Full-featured web interface for managing sources and search
• Horizontally Scalable: Deploy as a single container or scale to multiple nodes

(back to top)

Features

Category	Features
Data Sources	GitHub, GitLab, Slack, Notion, Confluence, Jira, Google Drive, Google Docs, Linear, Dropbox, S3
Search	Lexical (BM25), semantic embeddings, hybrid search, query expansion
Authentication	OAuth2 (GitHub, Google, etc.), JWT sessions, team management
API	RESTful API with OpenAPI/Swagger specification
Deployment	Docker, Docker Compose, Kubernetes (Helm charts coming soon)
UI	Admin dashboard for source management, search, and configuration

(back to top)

Built With

• - Go 1.24+
• - Database
• - Search engine
• - Containerization

(back to top)

Getting Started

Prerequisites

• Docker and Docker Compose
• 4GB+ RAM (Vespa requires memory)
• Ports: 8080 (API), 3000 (UI), 5432 (Postgres), 19071 (Vespa)

Quick Start

The fastest way to get started is using the quickstart example:

# Clone the repository
git clone https://github.com/sercha-oss/sercha-core.git
cd sercha-core/examples/quickstart

# Start services
docker compose up -d

Wait 1-2 minutes for Vespa to initialize, then:

• API: http://localhost:8080
• API Docs: http://localhost:8080/swagger/index.html

For detailed setup instructions, see the Quickstart Guide.

(back to top)

Architecture

Sercha Core uses a hexagonal (ports and adapters) architecture:

┌─────────────────────────────────────────────────────────────┐
│                        Sercha Core                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐  │
│   │   REST API  │     │   Worker    │     │  Scheduler  │  │
│   │   Handler   │     │   Tasks     │     │   (Cron)    │  │
│   └──────┬──────┘     └──────┬──────┘     └──────┬──────┘  │
│          │                   │                   │          │
│          └───────────────────┼───────────────────┘          │
│                              │                              │
│                    ┌─────────▼─────────┐                    │
│                    │   Core Services   │                    │
│                    │  (Business Logic) │                    │
│                    └─────────┬─────────┘                    │
│                              │                              │
│          ┌───────────────────┼───────────────────┐          │
│          │                   │                   │          │
│   ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐  │
│   │  PostgreSQL │     │    Vespa    │     │ Connectors  │  │
│   │  (Storage)  │     │  (Search)   │     │  (OAuth)    │  │
│   └─────────────┘     └─────────────┘     └─────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Deployment Modes

Mode	Use Case	Components
All-in-One	Development, small teams	Single binary: API + Worker + Scheduler

(back to top)

Deployment Examples

Pre-configured Docker Compose examples are available in the examples/ directory:

Example	Description	Use Case
quickstart/	Pre-built images from ghcr.io	Getting started, production
dev/	Builds from local Dockerfile	Active development

# Quickstart (pre-built images)
cd examples/quickstart
docker compose up -d

# Development (builds from source)
cd examples/dev
docker compose up -d

(back to top)

Configuration

Sercha Core is configured via environment variables:

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
VESPA_CONFIG_URL	Vespa config server URL	http://localhost:19071
VESPA_CONTAINER_URL	Vespa container URL	http://localhost:8080
JWT_SECRET	Secret for JWT token signing	Required
PORT	HTTP server port	8080
UI_BASE_URL	Admin UI URL (for OAuth redirects)	http://localhost:3000
CORS_ALLOWED_ORIGINS	Comma-separated allowed origins	http://localhost:3000

AI Configuration (Optional)

Variable	Description
EMBEDDING_PROVIDER	Embedding provider (openai, ollama)
EMBEDDING_MODEL	Model name for embeddings
EMBEDDING_API_KEY	API key for embedding provider
LLM_PROVIDER	LLM provider for query expansion
LLM_MODEL	Model name for LLM
LLM_API_KEY	API key for LLM provider

For complete configuration options, see Configuration Reference.

(back to top)

API Documentation

Sercha Core provides a full REST API with OpenAPI specification:

• Swagger UI: http://localhost:8080/swagger/index.html (when running)
• OpenAPI Spec: swagger/swagger.yaml
• API Reference: docs.sercha.dev/core/api_reference

Example: Search API

curl -X POST http://localhost:8080/api/v1/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication flow", "limit": 10}'

(back to top)

Development

Prerequisites

• Go 1.24+
• Node.js 20+ (for UI)
• Docker and Docker Compose

Local Development

# Terminal 1: Start backend (builds from source)
cd examples/dev
docker compose up -d

# Terminal 2: Start UI with hot reload
cd ui
npm install
npm run dev   # http://localhost:3001

The Next.js dev server automatically proxies /api/* requests to the backend.

Running Tests

# Unit tests
go test ./...

# Integration tests
cd tests/integration
make test

Building

# Backend
go build -o sercha-core ./cmd/sercha-core

# UI (static export)
cd ui && npm run build

For detailed development instructions, see CONTRIBUTING.md.

(back to top)

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

Please read:

• Contributing Guide - Development workflow and guidelines
• Security Policy - Reporting security vulnerabilities

Quick Links

• Open Issues
• Pull Requests

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE for details.

(back to top)