Skip to content

Izabella assistant. Architecture & Services

Written by:

Igor Gorovyy
DevOps Engineer Lead & Senior Solutions Architect

LinkedIn

w

🧠 Izabella assistant. Architecture & Services

📦 Services Summary

1. content-service

  • Purpose: REST API for managing Markdown pages and JD structure.
  • Exposes endpoints for CRUD operations.
  • Includes JD classification integration and preview rendering.

2. embedding-worker

  • Purpose: Background worker that handles embedding generation using OpenAI.
  • Consumes messages from a queue and writes vectors to Qdrant or Weaviate.

3. vector-api

  • Purpose: Vector search endpoint that allows querying semantically relevant content.
  • Provides top-k semantic search and supports JD-based filtering.

4. auth-service

  • Purpose: Handles authentication and RBAC enforcement using OIDC and JWT.
  • Maps user roles to JD scopes for permission management.

5. gitops-listener

  • Purpose: Watches file system or Git changes to auto-trigger embedding re-indexing.
  • Ensures content in Git stays in sync with the vector search index.

🧾 config.go Template

package config

import (
    "log"
    "os"
    "github.com/joho/godotenv"
)

func LoadEnv() {
    err := godotenv.Load()
    if err != nil {
        log.Println("[INFO] .env file not found, relying on system envs")
    }
}

func Get(key string, fallback string) string {
    if value, exists := os.LookupEnv(key); exists {
        return value
    }
    return fallback
}

Usage in main.go:

import "your/module/config"

func main() {
    config.LoadEnv()
    port := config.Get("PORT", "8080")
    ...
}

📁 go.mod for Services

Example (content-service/go.mod)

module github.com/your-org/content-service

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/joho/godotenv v1.5.1
)

📄 README.md Example

Example (embedding-worker/README.md)

# 🧠 Embedding Worker

This service listens to a message queue (Redis, SQS, etc.), extracts Markdown content,
sends it to OpenAI for embeddings, and stores the results in Qdrant.

## Env Variables
- OPENAI_API_KEY
- VECTORDB_URL
- QUEUE_URL

🔁 GitHub Actions CI Template

# .github/workflows/ci.yaml
name: Go Services CI

on:
  push:
    paths:
      - '**/*.go'
      - '**/go.mod'
      - '**/go.sum'

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: [content-service, embedding-worker, vector-api, auth-service, gitops-listener]
    defaults:
      run:
        working-directory: ${{ matrix.service }}
    steps:
      - uses: actions/checkout@v3
      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: 1.21
      - name: Tidy
        run: go mod tidy
      - name: Build
        run: go build ./...
      - name: Test
        run: go test ./...

🐳 Dockerfile Template

FROM golang:1.21-alpine

WORKDIR /app
COPY . .
RUN go mod tidy && go build -o app .

CMD ["./app"]

🧰 devcontainer.json for VS Code

{
  "name": "JD Knowledge Dev",
  "image": "mcr.microsoft.com/devcontainers/go:1.21",
  "features": {
    "ghcr.io/devcontainers/features/go:1": {
      "version": "1.21"
    }
  },
  "customizations": {
    "vscode": {
      "extensions": ["golang.Go", "eamodio.gitlens"]
    }
  }
}

🌍 .env Template for All Services

# content-service
PORT=8080
STORAGE_PATH=./data
JD_YAML=./config/jd.yaml

# embedding-worker
OPENAI_API_KEY=your-key
VECTORDB_URL=http://qdrant:6333
QUEUE_URL=redis://localhost:6379

# vector-api
PORT=8090
VECTORDB_URL=http://qdrant:6333

# auth-service
PORT=8081
OIDC_PROVIDER_URL=https://auth.example.com
JWT_SECRET=your-secret

# gitops-listener
WATCH_DIR=./knowledgebase
TRIGGER_URL=http://embedding-worker:8080/reindex

📑 Swagger (OpenAPI) for content-service

openapi: 3.0.0
info:
  title: Content Service API
  version: 1.0.0
paths:
  /pages:
    get:
      summary: List all pages
      responses:
        '200':
          description: A JSON array of pages
    post:
      summary: Create a new page
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Page'
      responses:
        '201':
          description: Created

  /pages/{id}:
    get:
      summary: Get a single page
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single page
    put:
      summary: Update a page
      responses:
        '200':
          description: Updated
    delete:
      summary: Delete a page
      responses:
        '204':
          description: Deleted

components:
  schemas:
    Page:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        content:
          type: string
        jd_code:
          type: string
        jd_path:
          type: string