# monuchaudhary14/archon architecture

> Architecture diagram of the GitHub repository monuchaudhary14/archon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monuchaudhary14/archon
- Repository: https://github.com/monuchaudhary14/archon

## Overview

Archon combines a Go system-design interview platform with a Python AI engine. Users authenticate, select or enter an interview, collaborate in a live chat/diagram session, and can later review evaluation reports and progress. The Go server wires authenticated API domains and a WebSocket AI session; the AI engine consumes Kafka events, generates interview responses, and dispatches evaluation work to Temporal. The graph includes documented core AI services and Go product domains, but source excerpts do not establish every internal call or all unsampled subsystem wiring.

Main entry points: [`internal/server/server.go`](https://github.com/monuchaudhary14/archon/blob/main/internal/server/server.go) (HTTP API Server), [`ai_engine/app/services/llm_service.py`](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/llm_service.py) (LLM Interviewer), [`internal/ai/handler.go`](https://github.com/monuchaudhary14/archon/blob/main/internal/ai/handler.go) (Live AI Chat), [`ai_engine/app/workflows/worker.py`](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/worker.py) (Temporal Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_go_platform["Go Platform"]
  node_api_server["HTTP API Server<br/>[server.go]"]
  node_auth["Authentication<br/>[routes.go]"]
  node_pg[("PostgreSQL")]
  node_redis[("Redis")]
end

subgraph group_interview["Interview Experience"]
  node_interviews["Interview Sessions<br/>[handler.go]"]
  node_live_chat["Live AI Chat<br/>[handler.go]"]
  node_diagram["Interview Diagrams<br/>[handler.go]"]
  node_ai_processor["Session Processor"]
  node_ai_kafka_go["AI Kafka Bridge<br/>[kafka.go]"]
end

subgraph group_progress["Progress &amp; Content"]
  node_dashboard["Dashboard<br/>[handler.go]"]
  node_analytics["Analytics<br/>[handler.go]"]
  node_reports["Evaluation Reports<br/>[handler.go]"]
  node_quiz["Practice Quizzes<br/>[handler.go]"]
  node_settings["User Settings<br/>[handler.go]"]
end

subgraph group_ai_runtime["AI Runtime"]
  node_ai_boot["AI Service Runtime<br/>[main.py]"]
  node_kafka_consumer["Kafka Consumer<br/>[kafka_service.py]"]
  node_llm["LLM Interviewer<br/>[llm_service.py]"]
  node_knowledge["Knowledge Search"]
  node_diagram_ai["Diagram Critique<br/>[diagram_service.py]"]
  node_interview_store["Interview Context"]
  node_key_rotation["LLM Key Rotation<br/>[key_rotator.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_temporal_worker["Temporal Worker<br/>[worker.py]"]
  node_workflow["Evaluation Workflow"]
  node_activities["Evaluation Activities<br/>[activities.py]"]
  node_contracts["Workflow Contracts<br/>[contracts.py]"]
end

node_user(("Candidate"))
node_kafka["Kafka"]
node_temporal["Temporal Service"]
node_llm_provider["LLM Provider"]

node_user -->|"uses API"| node_api_server
node_api_server -->|"registers routes"| node_auth
node_api_server -->|"registers routes"| node_interviews
node_api_server -->|"sets up AI"| node_live_chat
node_api_server -->|"registers routes"| node_dashboard
node_api_server -->|"registers routes"| node_analytics
node_api_server -->|"registers routes"| node_reports
node_api_server -->|"registers routes"| node_quiz
node_api_server -->|"registers routes"| node_settings
node_api_server -->|"opens pool"| node_pg
node_api_server -->|"creates client"| node_redis
node_user -->|"opens WebSocket"| node_live_chat
node_live_chat -->|"processes session"| node_ai_processor
node_live_chat -->|"authenticates user"| node_auth
node_live_chat -->|"checks ownership"| node_diagram
node_interviews -.->|"persists sessions"| node_pg
node_dashboard -->|"queries progress"| node_pg
node_reports -->|"reads interview results"| node_pg
node_ai_boot -->|"creates service"| node_llm
node_ai_boot -->|"starts consumer"| node_kafka_consumer
node_ai_boot -->|"starts worker"| node_temporal_worker
node_kafka_consumer -->|"generates responses"| node_llm
node_kafka_consumer -->|"starts evaluation"| node_temporal_worker
node_kafka_consumer -.->|"consumes events"| node_kafka
node_ai_kafka_go -.->|"exchanges events"| node_kafka
node_temporal_worker -->|"connects worker"| node_temporal
node_temporal_worker -->|"registers workflow"| node_workflow
node_temporal_worker -->|"registers activities"| node_activities
node_workflow -->|"runs activities"| node_activities
node_workflow -->|"uses inputs"| node_contracts
node_activities -->|"searches rubrics"| node_knowledge
node_llm -->|"rotates credentials"| node_key_rotation
node_llm -.->|"invokes model"| node_llm_provider
node_llm -.->|"uses context"| node_knowledge
node_llm -.->|"uses critique"| node_diagram_ai
node_llm -.->|"uses context store"| node_interview_store

click node_api_server "https://github.com/monuchaudhary14/archon/blob/main/internal/server/server.go"
click node_auth "https://github.com/monuchaudhary14/archon/blob/main/internal/auth/routes.go"
click node_interviews "https://github.com/monuchaudhary14/archon/blob/main/internal/interview/handler.go"
click node_live_chat "https://github.com/monuchaudhary14/archon/blob/main/internal/ai/handler.go"
click node_diagram "https://github.com/monuchaudhary14/archon/blob/main/internal/diagram/handler.go"
click node_ai_processor "https://github.com/monuchaudhary14/archon/blob/main/internal/ai/session_processor.go"
click node_ai_kafka_go "https://github.com/monuchaudhary14/archon/blob/main/internal/ai/kafka.go"
click node_dashboard "https://github.com/monuchaudhary14/archon/blob/main/internal/dashboard/handler.go"
click node_analytics "https://github.com/monuchaudhary14/archon/blob/main/internal/analytics/handler.go"
click node_reports "https://github.com/monuchaudhary14/archon/blob/main/internal/reports/handler.go"
click node_quiz "https://github.com/monuchaudhary14/archon/blob/main/internal/quiz/handler.go"
click node_settings "https://github.com/monuchaudhary14/archon/blob/main/internal/settings/handler.go"
click node_ai_boot "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/main.py"
click node_kafka_consumer "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/kafka_service.py"
click node_llm "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/llm_service.py"
click node_knowledge "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/knowledge_service.py"
click node_diagram_ai "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/diagram_service.py"
click node_interview_store "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/interview_repository.py"
click node_key_rotation "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/core/key_rotator.py"
click node_temporal_worker "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/worker.py"
click node_workflow "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/evaluation_workflow.py"
click node_activities "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/activities.py"
click node_contracts "https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/contracts.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_server,node_auth,node_pg,node_redis toneBlue
class node_interviews,node_live_chat,node_diagram,node_ai_processor,node_ai_kafka_go toneAmber
class node_dashboard,node_analytics,node_reports,node_quiz,node_settings toneMint
class node_ai_boot,node_kafka_consumer,node_llm,node_knowledge,node_diagram_ai,node_interview_store,node_key_rotation toneRose
class node_temporal_worker,node_workflow,node_activities,node_contracts,node_user,node_kafka,node_temporal,node_llm_provider toneIndigo
```

## Components

### Go Platform

- [HTTP API Server](https://github.com/monuchaudhary14/archon/blob/main/internal/server/server.go): `internal/server/server.go`
- [Authentication](https://github.com/monuchaudhary14/archon/blob/main/internal/auth/routes.go): `internal/auth/routes.go`
- **PostgreSQL**
- **Redis**

### Interview Experience

- [Interview Sessions](https://github.com/monuchaudhary14/archon/blob/main/internal/interview/handler.go): `internal/interview/handler.go`
- [Live AI Chat](https://github.com/monuchaudhary14/archon/blob/main/internal/ai/handler.go): `internal/ai/handler.go`
- [Interview Diagrams](https://github.com/monuchaudhary14/archon/blob/main/internal/diagram/handler.go): `internal/diagram/handler.go`
- [Session Processor](https://github.com/monuchaudhary14/archon/blob/main/internal/ai/session_processor.go): `internal/ai/session_processor.go`
- [AI Kafka Bridge](https://github.com/monuchaudhary14/archon/blob/main/internal/ai/kafka.go): `internal/ai/kafka.go`

### Progress & Content

- [Dashboard](https://github.com/monuchaudhary14/archon/blob/main/internal/dashboard/handler.go): `internal/dashboard/handler.go`
- [Analytics](https://github.com/monuchaudhary14/archon/blob/main/internal/analytics/handler.go): `internal/analytics/handler.go`
- [Evaluation Reports](https://github.com/monuchaudhary14/archon/blob/main/internal/reports/handler.go): `internal/reports/handler.go`
- [Practice Quizzes](https://github.com/monuchaudhary14/archon/blob/main/internal/quiz/handler.go): `internal/quiz/handler.go`
- [User Settings](https://github.com/monuchaudhary14/archon/blob/main/internal/settings/handler.go): `internal/settings/handler.go`

### AI Runtime

- [AI Service Runtime](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/main.py): `ai_engine/app/main.py`
- [Kafka Consumer](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/kafka_service.py): `ai_engine/app/services/kafka_service.py`
- [LLM Interviewer](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/llm_service.py): `ai_engine/app/services/llm_service.py`
- [Knowledge Search](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/knowledge_service.py): `ai_engine/app/services/knowledge_service.py`
- [Diagram Critique](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/diagram_service.py): `ai_engine/app/services/diagram_service.py`
- [Interview Context](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/services/interview_repository.py): `ai_engine/app/services/interview_repository.py`
- [LLM Key Rotation](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/core/key_rotator.py): `ai_engine/app/core/key_rotator.py`

### Evaluation

- [Temporal Worker](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/worker.py): `ai_engine/app/workflows/worker.py`
- [Evaluation Workflow](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/evaluation_workflow.py): `ai_engine/app/workflows/evaluation_workflow.py`
- [Evaluation Activities](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/activities.py): `ai_engine/app/workflows/activities.py`
- [Workflow Contracts](https://github.com/monuchaudhary14/archon/blob/main/ai_engine/app/workflows/contracts.py): `ai_engine/app/workflows/contracts.py`

### Other components

- **Candidate**
- **Kafka**
- **Temporal Service**
- **LLM Provider**

## Connections

- Candidate → HTTP API Server: uses API (evidence: `internal/server/server.go`)
- HTTP API Server → Authentication: registers routes (evidence: `internal/server/server.go`)
- HTTP API Server → Interview Sessions: registers routes (evidence: `internal/server/server.go`)
- HTTP API Server → Live AI Chat: sets up AI (evidence: `internal/server/server.go`)
- HTTP API Server → Dashboard: registers routes (evidence: `internal/server/server.go`)
- HTTP API Server → Analytics: registers routes (evidence: `internal/server/server.go`)
- HTTP API Server → Evaluation Reports: registers routes (evidence: `internal/server/server.go`)
- HTTP API Server → Practice Quizzes: registers routes (evidence: `internal/server/server.go`)
- HTTP API Server → User Settings: registers routes (evidence: `internal/server/server.go`)
- HTTP API Server → PostgreSQL: opens pool (evidence: `internal/server/server.go`)
- HTTP API Server → Redis: creates client (evidence: `internal/server/server.go`)
- Candidate → Live AI Chat: opens WebSocket (evidence: `internal/ai/handler.go`)
- Live AI Chat → Session Processor: processes session (evidence: `internal/ai/handler.go`)
- Live AI Chat → Authentication: authenticates user (evidence: `internal/ai/handler.go`)
- Live AI Chat → Interview Diagrams: checks ownership (evidence: `internal/ai/handler.go`)
- Interview Sessions → PostgreSQL: persists sessions
- Dashboard → PostgreSQL: queries progress
- Evaluation Reports → PostgreSQL: reads interview results
- AI Service Runtime → LLM Interviewer: creates service (evidence: `ai_engine/app/main.py`)
- AI Service Runtime → Kafka Consumer: starts consumer (evidence: `ai_engine/app/main.py`)
- AI Service Runtime → Temporal Worker: starts worker (evidence: `ai_engine/app/main.py`)
- Kafka Consumer → LLM Interviewer: generates responses (evidence: `ai_engine/app/services/kafka_service.py`)
- Kafka Consumer → Temporal Worker: starts evaluation (evidence: `ai_engine/app/services/kafka_service.py`)
- Kafka Consumer → Kafka: consumes events
- AI Kafka Bridge → Kafka: exchanges events
- Temporal Worker → Temporal Service: connects worker (evidence: `ai_engine/app/workflows/worker.py`)
- Temporal Worker → Evaluation Workflow: registers workflow (evidence: `ai_engine/app/workflows/worker.py`)
- Temporal Worker → Evaluation Activities: registers activities (evidence: `ai_engine/app/workflows/worker.py`)
- Evaluation Workflow → Evaluation Activities: runs activities (evidence: `ai_engine/app/workflows/evaluation_workflow.py`)
- Evaluation Workflow → Workflow Contracts: uses inputs (evidence: `ai_engine/app/workflows/evaluation_workflow.py`)
- Evaluation Activities → Knowledge Search: searches rubrics (evidence: `ai_engine/app/workflows/activities.py`)
- LLM Interviewer → LLM Key Rotation: rotates credentials (evidence: `ai_engine/app/services/llm_service.py`)
- LLM Interviewer → LLM Provider: invokes model
- LLM Interviewer → Knowledge Search: uses context (evidence: `ai_engine/app/services/llm_service.py`)
- LLM Interviewer → Diagram Critique: uses critique (evidence: `ai_engine/app/services/llm_service.py`)
- LLM Interviewer → Interview Context: uses context store (evidence: `ai_engine/app/services/llm_service.py`)