# durmazfurkann/jira-task-assignment-system architecture

> Architecture diagram of the GitHub repository durmazfurkann/jira-task-assignment-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/durmazfurkann/jira-task-assignment-system
- Repository: https://github.com/durmazfurkann/jira-task-assignment-system

## Overview

1. This repo is a Jira task assignment platform with three core runtime pieces: a Hono-based backend API, a React/Vite admin panel, and external automation through n8n/Jira webhooks. The backend is the system of record and scoring engine; the admin UI is for operators; n8n is the inbound trigger path for live Jira events.

2. The primary request flow starts when Jira emits an “issue created” webhook. n8n receives that event, filters out already-assigned issues, and calls the backend’s `/assignments/execute` endpoint with the normalized issue payload. That endpoint evaluates candidates, persists the recommendation/log, and can optionally write the chosen assignee back to Jira.

3. The backend API lives under `app/api` and is organized by domain routes: assignments, auth, employees, config, api keys, logs, sync, jira, dashboard, and admin-preview. Authentication is split by use case: JWT middleware protects admin-only routes, while `X-Api-Key` middleware protects assignment execution/preview endpoints intended for n8n or other integrations.

4. Persistence is PostgreSQL, defined in `database/schema.sql` and preloaded with defaults in `database/seed.sql`. The database stores employees, assignment logs, configuration, API keys, and sync state. It is the operational data store for the admin panel and the backend’s decision audit trail.

5. Semantic history is stored separately in Qdrant. Completed Jira tasks are embedded and indexed there, so the system can perform similarity search against past work when scoring a new issue. This is the “RAG-style” memory layer that supplements rule-based skill matching.

6. Ollama is the local LLM dependency used during sync for employee skill and role inference, and also as an embedding provider by default. Syncing Jira history is therefore a multi-step enrichment pipeline: fetch Jira data, normalize it, embed completed tasks into Qdrant, and infer/update employee profiles from the historical task set.

7. The scoring subsystem is centered in `app/scoring/score-task.ts` and related services. Candidate ranking combines technical fit, historical fit from vector similarity, workload balance, and a confidence factor. The config page in the admin panel adjusts the weighting parameters that shape this final score.

8. Jira integration is encapsulated in `app/services/jira-client.ts`, `normalize-jira-issue.ts`, and `jira-sync.ts`. One path handles live assignment and optional issue commenting/assignment in Jira; another path handles bulk or incremental synchronization of historical issues to build the employee model and semantic index.

9. The admin application under `admin/` is a separate frontend built with React, TypeScript, and Vite, then served via nginx in its own Docker image. It provides protected operational views for dashboard, employees, API keys, config, logs, preview, sync, Jira-related pages, and a three-step agent flow for task evaluation.

10. The admin panel talks directly to the backend API through a small client layer in `admin/src/api/client.ts`. Login establishes JWT-based access for protected pages, while API key management supports external integrations. This separates human operator actions from machine-triggered assignment execution.

11. Infrastructure is containerized with Docker and docker-compose. The backend expects PostgreSQL, Qdrant, and optionally Ollama to be reachable, while the admin UI is a static frontend container. The README also notes a Linux-specific `host.docker.internal` caveat for reaching host-based Ollama from containers.

12. There are two supporting automation paths outside the main runtime. `scripts/backtest.mjs` measures recommendation quality against historical Jira data, and `scripts/seed-jira-tasks.mjs` provides sample tasks. The `tests/` directory contains unit tests around auth, scoring, environment loading, and historical fit, which map directly to the system’s critical decision logic.

13. The repo also includes OpenAPI generation and documentation endpoints, plus sample n8n workflows under `n8n-workflows/`. Those artifacts make the backend an integration hub: external orchestration enters through webhook/API boundaries, while the admin UI and database provide observability and control over assignment behavior.

Main entry points: [`app/api/server.ts`](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/server.ts) (API server), [`app/scoring/score-task.ts`](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/scoring/score-task.ts) (Scoring), [`app/api/routes/assignments.ts`](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/assignments.ts) (Assignments), [`app/services/jira-sync.ts`](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/jira-sync.ts) (Jira sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Core runtime"]
  node_api_server["API server<br/>Hono backend<br/>[server.ts]"]
  node_auth_routes["Auth<br/>route module<br/>[auth.ts]"]
  node_assignment_routes["Assignments<br/>route module<br/>[assignments.ts]"]
  node_admin_preview_routes["Admin preview<br/>route module<br/>[admin-preview.ts]"]
  node_api_keys_routes["API keys<br/>route module<br/>[api-keys.ts]"]
  node_employees_routes["Employees<br/>route module<br/>[employees.ts]"]
  node_config_routes["Config<br/>route module<br/>[config.ts]"]
  node_logs_routes["Logs<br/>route module<br/>[logs.ts]"]
  node_sync_routes["Sync<br/>route module<br/>[sync.ts]"]
  node_jira_routes["Jira API<br/>route module<br/>[jira.ts]"]
  node_score_task["Scoring<br/>ranking service<br/>[score-task.ts]"]
  node_jira_sync["Jira sync<br/>sync pipeline<br/>[jira-sync.ts]"]
  node_create_preview["Preview engine<br/>decision service"]
end

subgraph group_admin["Admin UI"]
  node_admin_app["Admin app<br/>React/Vite frontend<br/>[App.tsx]"]
  node_admin_api_client["API client<br/>frontend client<br/>[client.ts]"]
  node_admin_pages["Admin pages<br/>ui pages<br/>[Dashboard.tsx]"]
  node_admin_agent["Agent flow<br/>ui workflow<br/>[TaskInputStep.tsx]"]
end

subgraph group_data["Data layer"]
  node_db_service[("Postgres<br/>database access<br/>[db.ts]")]
  node_qdrant_service[("Qdrant<br/>vector store<br/>[qdrant.ts]")]
  node_schema_sql["Schema<br/>[schema.sql]"]
  node_seed_sql["Seed data<br/>sql seed<br/>[seed.sql]"]
end

subgraph group_integrations["External systems"]
  node_jira_client["Jira client<br/>integration service<br/>[jira-client.ts]"]
  node_normalize_issue["Normalize issue<br/>transform service"]
  node_llm_service["Ollama<br/>llm/embedding service<br/>[llm.ts]"]
  node_embedding_service["Embeddings<br/>vector service<br/>[embedding.ts]"]
end

subgraph group_automation["Supporting automation"]
  node_n8n_workflows["n8n flows<br/>workflow fixtures"]
  node_backtest_script["Backtest<br/>analysis script<br/>[backtest.mjs]"]
  node_seed_tasks_script["Seed tasks<br/>sample script"]
  node_tests_suite["Tests<br/>test suite<br/>[score-task.test.ts]"]
end

node_api_server -->|"mounts"| node_auth_routes
node_api_server -->|"mounts"| node_assignment_routes
node_api_server -->|"mounts"| node_admin_preview_routes
node_api_server -->|"mounts"| node_api_keys_routes
node_api_server -->|"mounts"| node_employees_routes
node_api_server -->|"mounts"| node_config_routes
node_api_server -->|"mounts"| node_logs_routes
node_api_server -->|"mounts"| node_sync_routes
node_api_server -->|"mounts"| node_jira_routes
node_assignment_routes -->|"uses"| node_score_task
node_assignment_routes -->|"uses"| node_create_preview
node_create_preview -->|"calls"| node_score_task
node_sync_routes -->|"triggers"| node_jira_sync
node_jira_sync -->|"fetches"| node_jira_client
node_jira_sync -->|"infers"| node_llm_service
node_jira_sync -->|"embeds"| node_embedding_service
node_embedding_service -->|"stores"| node_qdrant_service
node_score_task -->|"queries"| node_qdrant_service
node_score_task -->|"reads/writes"| node_db_service
node_db_service -->|"defined by"| node_schema_sql
node_db_service -->|"preloaded by"| node_seed_sql
node_admin_app -->|"calls"| node_admin_api_client
node_admin_app -->|"renders"| node_admin_pages
node_admin_app -->|"renders"| node_admin_agent
node_admin_api_client -->|"requests"| node_api_server
node_n8n_workflows -->|"triggers"| node_assignment_routes
node_n8n_workflows -->|"integrates"| node_jira_routes
node_jira_client -->|"prepares"| node_normalize_issue
node_jira_client -->|"serves"| node_assignment_routes
node_tests_suite -->|"verifies"| node_score_task
node_tests_suite -->|"verifies"| node_auth_routes
node_backtest_script -->|"evaluates"| node_score_task
node_seed_tasks_script -->|"feeds"| node_jira_client

click node_api_server "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/server.ts"
click node_auth_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/auth.ts"
click node_assignment_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/assignments.ts"
click node_admin_preview_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/admin-preview.ts"
click node_api_keys_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/api-keys.ts"
click node_employees_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/employees.ts"
click node_config_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/config.ts"
click node_logs_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/logs.ts"
click node_sync_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/sync.ts"
click node_jira_routes "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/jira.ts"
click node_score_task "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/scoring/score-task.ts"
click node_jira_sync "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/jira-sync.ts"
click node_create_preview "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/create-assignment-preview.ts"
click node_jira_client "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/jira-client.ts"
click node_normalize_issue "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/normalize-jira-issue.ts"
click node_llm_service "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/llm.ts"
click node_embedding_service "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/embedding.ts"
click node_db_service "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/db.ts"
click node_qdrant_service "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/qdrant.ts"
click node_schema_sql "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/database/schema.sql"
click node_seed_sql "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/database/seed.sql"
click node_admin_app "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/App.tsx"
click node_admin_api_client "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/api/client.ts"
click node_admin_pages "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/pages/Dashboard.tsx"
click node_admin_agent "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/pages/agent/TaskInputStep.tsx"
click node_n8n_workflows "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/n8n-workflows/jira-task-assignment-webhook.json"
click node_backtest_script "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/scripts/backtest.mjs"
click node_seed_tasks_script "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/scripts/seed-jira-tasks.mjs"
click node_tests_suite "https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/tests/score-task.test.ts"

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_routes,node_assignment_routes,node_admin_preview_routes,node_api_keys_routes,node_employees_routes,node_config_routes,node_logs_routes,node_sync_routes,node_jira_routes,node_score_task,node_jira_sync,node_create_preview toneBlue
class node_admin_app,node_admin_api_client,node_admin_pages,node_admin_agent toneAmber
class node_db_service,node_qdrant_service,node_schema_sql,node_seed_sql toneMint
class node_jira_client,node_normalize_issue,node_llm_service,node_embedding_service toneRose
class node_n8n_workflows,node_backtest_script,node_seed_tasks_script,node_tests_suite toneIndigo
```

## Components

### Core runtime

Backend API, scoring, and sync logic that execute assignment decisions.

- [API server](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/server.ts): Hono backend · Composes middleware and route modules into the main backend service. · `app/api/server.ts`
- [Auth](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/auth.ts): route module · Login and session entrypoints for operator access. · `app/api/routes/auth.ts`
- [Assignments](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/assignments.ts): route module · Executes task assignment and preview flows. · `app/api/routes/assignments.ts`
- [Admin preview](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/admin-preview.ts): route module · Operator-facing preview path for evaluating recommendations. · `app/api/routes/admin-preview.ts`
- [API keys](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/api-keys.ts): route module · Manages keys used by external integrations. · `app/api/routes/api-keys.ts`
- [Employees](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/employees.ts): route module · CRUD and state for assignee profiles. · `app/api/routes/employees.ts`
- [Config](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/config.ts): route module · Reads and updates scoring and system parameters. · `app/api/routes/config.ts`
- [Logs](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/logs.ts): route module · Exposes assignment and sync audit history. · `app/api/routes/logs.ts`
- [Sync](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/sync.ts): route module · Triggers Jira history synchronization and enrichment. · `app/api/routes/sync.ts`
- [Jira API](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/api/routes/jira.ts): route module · Jira integration endpoints for operational actions and callbacks. · `app/api/routes/jira.ts`
- [Scoring](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/scoring/score-task.ts): ranking service · Combines technical fit, historical fit, workload, and confidence into a final rank. · `app/scoring/score-task.ts`
- [Jira sync](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/jira-sync.ts): sync pipeline · Fetches Jira history and feeds the semantic and employee-model enrichment flow. · `app/services/jira-sync.ts`
- [Preview engine](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/create-assignment-preview.ts): decision service · Builds assignment previews without committing the final action. · `app/services/create-assignment-preview.ts`

### Admin UI

Operator-facing React application for monitoring and control.

- [Admin app](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/App.tsx): React/Vite frontend · Operator console for monitoring, configuration, and manual workflows. · `admin/src/App.tsx`
- [API client](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/api/client.ts): frontend client · Small client layer used by the admin UI to call the backend. · `admin/src/api/client.ts`
- [Admin pages](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/pages/Dashboard.tsx): ui pages · Dashboard, employees, config, logs, sync, preview, Jira, and API key screens. · `admin/src/pages/Dashboard.tsx`
- [Agent flow](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/admin/src/pages/agent/TaskInputStep.tsx): ui workflow · Three-step task evaluation flow for operators. · `admin/src/pages/agent/TaskInputStep.tsx`

### Data layer

Operational and semantic stores used by the system.

- [Postgres](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/db.ts): database access · Persistence adapter for operational records and audit data. · `app/services/db.ts`
- [Qdrant](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/qdrant.ts): vector store · Stores completed task embeddings for semantic retrieval. · `app/services/qdrant.ts`
- [Schema](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/database/schema.sql): sql schema · Defines employees, logs, config, API keys, and sync state. · `database/schema.sql`
- [Seed data](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/database/seed.sql): sql seed · Preloads defaults for the operational database. · `database/seed.sql`

### External systems

Jira, n8n, and LLM/vector dependencies that feed or enrich the platform.

- [Jira client](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/jira-client.ts): integration service · Wraps Jira reads, comments, and assignee updates. · `app/services/jira-client.ts`
- [Normalize issue](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/normalize-jira-issue.ts): transform service · Converts raw Jira payloads into the internal assignment shape. · `app/services/normalize-jira-issue.ts`
- [Ollama](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/llm.ts): llm/embedding service · Local model dependency used for inference and embedding generation. · `app/services/llm.ts`
- [Embeddings](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/app/services/embedding.ts): vector service · Produces embeddings for semantic history and similarity search. · `app/services/embedding.ts`

### Supporting automation

Docs, workflows, scripts, and tests around the main runtime.

- [n8n flows](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/n8n-workflows/jira-task-assignment-webhook.json): workflow fixtures · Sample webhook and HTTP workflows that trigger live assignments. · `n8n-workflows/jira-task-assignment-webhook.json`
- [Backtest](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/scripts/backtest.mjs): analysis script · Measures recommendation quality against historical Jira data. · `scripts/backtest.mjs`
- [Seed tasks](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/scripts/seed-jira-tasks.mjs): sample script · Generates sample Jira task data for local usage. · `scripts/seed-jira-tasks.mjs`
- [Tests](https://github.com/durmazfurkann/jira-task-assignment-system/blob/main/tests/score-task.test.ts): test suite · Covers auth, scoring, environment loading, and historical fit. · `tests/score-task.test.ts`

## Connections

- API server → Auth: mounts · Registers authentication routes on the backend.
- API server → Assignments: mounts · Registers assignment execution routes.
- API server → Admin preview: mounts · Registers operator preview endpoints.
- API server → API keys: mounts · Registers API key management routes.
- API server → Employees: mounts · Registers employee management routes.
- API server → Config: mounts · Registers config routes.
- API server → Logs: mounts · Registers audit/log routes.
- API server → Sync: mounts · Registers sync control routes.
- API server → Jira API: mounts · Registers Jira integration routes.
- Assignments → Scoring: uses · Ranks candidate assignees for a task.
- Assignments → Preview engine: uses · Builds preview or execution recommendations.
- Preview engine → Scoring: calls · Calculates the ranked candidate set.
- Sync → Jira sync: triggers · Starts bulk or incremental Jira synchronization.
- Jira sync → Jira client: fetches · Pulls Jira issues and history.
- Jira sync → Ollama: infers · Derives employee skills and roles from history.
- Jira sync → Embeddings: embeds · Creates vectors for completed tasks.
- Embeddings → Qdrant: stores · Writes semantic history for similarity search.
- Scoring → Qdrant: queries · Uses vector similarity as historical fit input.
- Scoring → Postgres: reads/writes · Consumes operational state and persists decision data.
- Postgres → Schema: defined by · Database structure comes from the SQL schema.
- Postgres → Seed data: preloaded by · Initial operational defaults come from seed data.
- Admin app → API client: calls · Uses the client layer to reach backend APIs.
- Admin app → Admin pages: renders · Hosts the operator screens.
- Admin app → Agent flow: renders · Hosts the task evaluation workflow.
- API client → API server: requests · Admin UI talks to the backend over HTTP.
- n8n flows → Assignments: triggers · Webhook and HTTP automation call assignment execution.
- n8n flows → Jira API: integrates · Workflows can also coordinate Jira-side actions.
- Jira client → Normalize issue: prepares · Transforms raw Jira payloads for internal use.
- Jira client → Assignments: serves · Supports live assignment and optional Jira writes.
- Tests → Scoring: verifies · Covers ranking and historical fit behavior.
- Tests → Auth: verifies · Covers auth-related behavior.
- Backtest → Scoring: evaluates · Compares scoring quality against historical issues.
- Seed tasks → Jira client: feeds · Provides sample Jira-like task data.
