How durmazfurkann/jira-task-assignment-system works
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: server.ts API server · score-task.ts Scoring · assignments.ts Assignments · jira-sync.ts Jira sync
Components 29
Core runtime
Backend API, scoring, and sync logic that execute assignment decisions.
- API server · Composes middleware and route modules into the main backend service.
app/api/server.ts - Auth · Login and session entrypoints for operator access.
app/api/routes/auth.ts - Assignments · Executes task assignment and preview flows.
app/api/routes/assignments.ts - Admin preview · Operator-facing preview path for evaluating recommendations.
app/api/routes/admin-preview.ts - API keys · Manages keys used by external integrations.
app/api/routes/api-keys.ts - Employees · CRUD and state for assignee profiles.
app/api/routes/employees.ts - Config · Reads and updates scoring and system parameters.
app/api/routes/config.ts - Logs · Exposes assignment and sync audit history.
app/api/routes/logs.ts - Sync · Triggers Jira history synchronization and enrichment.
app/api/routes/sync.ts - Jira API · Jira integration endpoints for operational actions and callbacks.
app/api/routes/jira.ts - Scoring · Combines technical fit, historical fit, workload, and confidence into a final rank.
app/scoring/score-task.ts - Jira sync · Fetches Jira history and feeds the semantic and employee-model enrichment flow.
app/services/jira-sync.ts - Preview engine · 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 · Operator console for monitoring, configuration, and manual workflows.
admin/src/App.tsx - API client · Small client layer used by the admin UI to call the backend.
admin/src/api/client.ts - Admin pages · Dashboard, employees, config, logs, sync, preview, Jira, and API key screens.
admin/src/pages/Dashboard.tsx - Agent flow · Three-step task evaluation flow for operators.
admin/src/pages/agent/TaskInputStep.tsx
Data layer
Operational and semantic stores used by the system.
- Postgres · Persistence adapter for operational records and audit data.
app/services/db.ts - Qdrant · Stores completed task embeddings for semantic retrieval.
app/services/qdrant.ts - Schema · Defines employees, logs, config, API keys, and sync state.
database/schema.sql - Seed data · 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 · Wraps Jira reads, comments, and assignee updates.
app/services/jira-client.ts - Normalize issue · Converts raw Jira payloads into the internal assignment shape.
app/services/normalize-jira-issue.ts - Ollama · Local model dependency used for inference and embedding generation.
app/services/llm.ts - Embeddings · 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 · Sample webhook and HTTP workflows that trigger live assignments.
n8n-workflows/jira-task-assignment-webhook.json - Backtest · Measures recommendation quality against historical Jira data.
scripts/backtest.mjs - Seed tasks · Generates sample Jira task data for local usage.
scripts/seed-jira-tasks.mjs - Tests · Covers auth, scoring, environment loading, and historical fit.
tests/score-task.test.ts
Connections 33
- 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.