Izabella assistant. C4 Architecture

Written by:

Igor Gorovyy
DevOps Engineer Lead & Senior Solutions Architect

LinkedIn

---

🧠 C4 Architecture

This document provides a full C4-style architecture overview for the JD-based Markdown + Vector knowledge system, built in Go.

---

🧭 C1 – System Context Diagram

graph TD
  User["User (Dev, Analyst)"]
  System["JD Knowledge Platform"]

  User -->|Read/Write| System

  subgraph External Systems
    Git["Git Repository"]
    OpenAI["OpenAI API"]
    Qdrant["Vector DB"]
    OIDC["OIDC Provider"]
  end

  System --> Git
  System --> OpenAI
  System --> Qdrant
  System --> OIDC

---

🧱 C2 – Container Diagram

graph TD
  subgraph JD Knowledge Platform
    UI["Web UI (Next.js/Vue)"]
    ContentAPI["content-service (Go API)"]
    VectorAPI["vector-api (Go API)"]
    EmbedWorker["embedding-worker (Go Worker)"]
    AuthService["auth-service (Go)"]
    GitOps["gitops-listener (Go)"]
  end

  User["User"] --> UI
  UI --> ContentAPI
  UI --> AuthService
  UI --> VectorAPI

  ContentAPI --> Storage[("Markdown + JD YAML")]
  ContentAPI --> Git["Git"]

  EmbedWorker --> OpenAI["OpenAI API"]
  EmbedWorker --> Qdrant["Vector DB"]

  VectorAPI --> Qdrant

  AuthService --> OIDC["OIDC Provider"]

  GitOps --> Git
  GitOps --> EmbedWorker

---

🧩 C3 – Component Diagram (content-service)

graph TD
  subgraph content-service
    APIHandler["HTTP Router (Gin)"]
    PageController["PageController"]
    JDClassifierClient["JD Classifier Client (LLM)"]
    MarkdownStore["Markdown File Store"]
    JDLoader["JD Structure Loader"]
  end

  APIHandler --> PageController
  PageController --> JDClassifierClient
  PageController --> MarkdownStore
  PageController --> JDLoader

---

🔧 C4 – Code-Level Structure (content-service)

classDiagram
  class main {
    +main()
  }

  class config.Config {
    +LoadEnv()
    +Get(key, fallback)
  }

  class handler.Router {
    +SetupRoutes()
  }

  class controller.PageController {
    +CreatePage()
    +GetPage()
    +UpdatePage()
    +DeletePage()
  }

  class jd.JDClassifierClient {
    +Classify(text) string
  }

  class storage.MarkdownStore {
    +SavePage()
    +LoadPage()
  }

  main --> config.Config
  main --> handler.Router
  handler.Router --> controller.PageController
  controller.PageController --> jd.JDClassifierClient
  controller.PageController --> storage.MarkdownStore

---

✅ Summary

This C4 model covers:

• The system in its external context (C1)
• Its main services as containers (C2)
• A breakdown of one core service (content-service) into components (C3)
• The internal code structure and Go modules layout (C4)

You can extend the component and code-level diagrams for other services as needed.

---

🧩 C3 – Component Diagram (embedding-worker)

graph TD
  subgraph embedding-worker
    QueueConsumer["Queue Listener (Redis/SQS)"]
    EmbeddingClient["OpenAI API Client"]
    Chunker["Markdown Chunker"]
    VectorWriter["Vector DB Writer"]
  end

  QueueConsumer --> Chunker
  Chunker --> EmbeddingClient
  EmbeddingClient --> VectorWriter

---

🔧 C4 – Code-Level Structure (embedding-worker)

classDiagram
  class main {
    +main()
  }

  class queue.Consumer {
    +Listen()
  }

  class embedding.OpenAIClient {
    +Embed(text string) []float32
  }

  class chunker.Chunker {
    +ChunkMarkdown(text string) []string
  }

  class vectordb.Writer {
    +WriteEmbedding()
  }

  main --> queue.Consumer
  queue.Consumer --> chunker.Chunker
  chunker.Chunker --> embedding.OpenAIClient
  embedding.OpenAIClient --> vectordb.Writer

---

🧩 C3 – Component Diagram (vector-api)

graph TD
  subgraph vector-api
    SearchController["Search Endpoint"]
    VectorClient["Qdrant/Weaviate Client"]
    FilterParser["JD Filter Parser"]
  end

  SearchController --> FilterParser
  FilterParser --> VectorClient

---

🔧 C4 – Code-Level Structure (vector-api)

classDiagram
  class main {
    +main()
  }

  class controller.SearchController {
    +HandleQuery()
  }

  class vectordb.Client {
    +QueryEmbedding()
  }

  class jd.FilterParser {
    +ParseJDFilter()
  }

  main --> controller.SearchController
  controller.SearchController --> jd.FilterParser
  jd.FilterParser --> vectordb.Client

---

🧩 C3 – Component Diagram (auth-service)

graph TD
  subgraph auth-service
    AuthController["Auth Endpoint"]
    JWTIssuer["JWT Token Issuer"]
    OIDCClient["OIDC Provider Client"]
    RoleMapper["JD Role Mapper"]
  end

  AuthController --> OIDCClient
  OIDCClient --> JWTIssuer
  JWTIssuer --> RoleMapper

---

🔧 C4 – Code-Level Structure (auth-service)

classDiagram
  class main {
    +main()
  }

  class controller.AuthController {
    +Login()
    +Callback()
  }

  class oidc.Client {
    +ExchangeCode()
  }

  class jwt.Issuer {
    +GenerateToken()
  }

  class jd.RoleMapper {
    +MapClaimsToJD()
  }

  main --> controller.AuthController
  controller.AuthController --> oidc.Client
  oidc.Client --> jwt.Issuer
  jwt.Issuer --> jd.RoleMapper

---

🧩 C3 – Component Diagram (gitops-listener)

graph TD
  subgraph gitops-listener
    FSWatcher["File System Watcher"]
    GitClient["Git Change Detector"]
    TriggerClient["Reindex Trigger Sender"]
  end

  FSWatcher --> GitClient
  GitClient --> TriggerClient

---

🔧 C4 – Code-Level Structure (gitops-listener)

classDiagram
  class main {
    +main()
  }

  class fs.Watcher {
    +WatchPath()
  }

  class git.Client {
    +DetectChanges()
  }

  class trigger.Client {
    +SendReindex()
  }

  main --> fs.Watcher
  fs.Watcher --> git.Client
  git.Client --> trigger.Client