Jira AI Assistant (Spring Boot + Spring AI)

Personal learning project: ingest Jira issues into PostgreSQL + pgvector, then answer questions using RAG (vector retrieval + Spring AI ChatClient) without calling Jira on every question.

Documentation

All deeper documentation lives under documentation/ (see documentation/README.md):

• Project overview
• Architecture & SOLID notes
• Development setup
• Application container (optional)
• Database ERD + ingestion rules
• REST API reference
• RAG design
• Jira integration
• MCP integration (optional)
• Security
• Roadmap

Architecture (short)

flowchart LR
  User[User / UI / curl] --> Api[Spring MVC]
  Api --> Ingest[Ingestion service]
  Api --> Rag[RAG assistant]
  Ingest --> Jira[Jira REST API]
  Ingest --> Emb[EmbeddingModel]
  Ingest --> Db[(PostgreSQL + pgvector)]
  Rag --> Emb
  Rag --> Db
  Rag --> Llm[ChatClient -> Ollama / OpenAI / Groq profile]

Loading

Prerequisites

• Java 21
• Maven 3.9+
• PostgreSQL with pgvector — provisioned outside this repo; see the sibling infra tree for deployment files and instructions.
• A reachable Jira instance and a Personal Access Token (PAT)
• Ollama and/or OpenAI / Groq (depending on APP_CHAT_PROVIDER / profiles), as described in Development setup

Quick start

1. Copy environment template

   cp .env.example .env

   Fill in real values locally (Jira, JDBC credentials matching your Postgres stack, LLM keys). Never commit .env.

2. Export environment variables for Spring Boot

   On Windows PowerShell you can use:

   Get-Content .env | ForEach-Object {
     if ($_ -match '^\s*#' -or $_ -notmatch '=') { return }
     $name, $value = $_.Split('=', 2)
     Set-Item -Path "Env:$($name.Trim())" -Value $value.Trim()
   }
   mvn spring-boot:run

   On Linux/macOS, many developers use export $(grep -v '^#' .env | xargs) (careful with spaces).

3. Ingest a ticket

   curl -X POST http://localhost:8080/jira/ingest/PROJ-123

4. Ask a grounded question

   curl -X POST http://localhost:8080/ai/ask ^
     -H "Content-Type: application/json" ^
     -d "{\"question\":\"What acceptance criteria are captured for PROJ-123?\"}"

5. Open the UI

   http://localhost:8080 includes a small chat page. Direct chat uses POST /api/chat. RAG uses POST /ai/ask.

6. Swagger UI (OpenAPI)

   With the app running: http://localhost:8080/swagger-ui.html
   Raw OpenAPI JSON: http://localhost:8080/v3/api-docs

Configuration rules (secrets)

• Never commit secrets (tokens, API keys, DB passwords).
• This repository intentionally does not ship real credentials.
• Use environment variables (or a local gitignored application-local.yml) for all secrets and environment-specific URLs.
• Startup validates required settings and fails fast with a clear error message if something critical is missing.

See SECURITY.md for details.

Required environment variables (minimum)

Variable	Purpose
JIRA_BASE_URL	Jira base URL (no trailing slash), e.g. https://jira.example.com
JIRA_PAT	Jira Personal Access Token (sent as Authorization: Bearer ...)
SPRING_DATASOURCE_URL	JDBC URL, e.g. jdbc:postgresql://localhost:5432/jiraai
SPRING_DATASOURCE_USERNAME	DB user
SPRING_DATASOURCE_PASSWORD	DB password

Additional requirements depend on profiles/providers:

• OPENAI_API_KEY when APP_CHAT_PROVIDER=openai or APP_EMBEDDING_PROVIDER=openai
• GROQ_API_KEY when Spring profile groq is active

See .env.example for the full list of commonly used variables.

Build commands

mvn clean package
mvn spring-boot:run
mvn test

License / learning intent

This is a personal learning codebase: production hardening (authn/z for the API, multi-tenant isolation, observability, etc.) is out of scope unless you choose to extend it.