lipad/chista-backend repository overview

⁠CHISTA Backend

CHISTA is a platform for exploring and understanding knowledge from existing software systems.

The backend provides services for:

• project and source management
• source-code analysis
• code symbols and relationships
• knowledge graph access
• semantic knowledge retrieval
• external source integrations
• AI-assisted analysis

⁠Technology

The backend is built with:

Java 21
Spring Boot
PostgreSQL
Neo4j
Qdrant
S3-compatible Object Storage
Ollama / Spring AI

⁠Docker Image

docker pull lipad/chista-backend:latest

Supported image architectures:

linux/amd64
linux/arm64

⁠Recommended Usage

The backend is part of a multi-service application.

Running the backend image alone is usually not sufficient because CHISTA also requires supporting infrastructure.

Use the Docker Compose configuration from the repository.

cp infrastructure/.env.example infrastructure/.env

Then:

docker compose \
  --env-file infrastructure/.env \
  -f infrastructure/compose.yaml \
  --profile app \
  up -d --no-build

If the frontend and backend should be built from the local repository instead:

docker compose \
  --env-file infrastructure/.env \
  -f infrastructure/compose.yaml \
  --profile app \
  up -d --build

⁠Supporting Services

The current Compose environment includes:

PostgreSQL
Neo4j
SeaweedFS
Qdrant
CHISTA Backend
CHISTA Frontend

Ollama can run separately and is configured through the backend environment.

⁠Object Storage

CHISTA uses an S3-compatible object-storage abstraction.

The local Compose environment uses:

SeaweedFS

The backend communicates with it through the S3 API.

Internally, the current Java implementation uses the MinIO Java SDK as an S3 client.

CHISTA's application layer itself depends on FileStoragePort, not directly on SeaweedFS.

⁠Port

The backend listens on:

8081

In the standard full-stack setup the browser normally uses the frontend entry point on port 8080.

Nginx forwards /api/* requests to the backend.

⁠Configuration

Runtime configuration is supplied through environment variables.

Examples:

SPRING_DATASOURCE_URL
SPRING_DATASOURCE_USERNAME
SPRING_DATASOURCE_PASSWORD

SPRING_NEO4J_URI
SPRING_NEO4J_AUTHENTICATION_USERNAME
SPRING_NEO4J_AUTHENTICATION_PASSWORD

LEGACYHUB_STORAGE_S3_ENDPOINT
LEGACYHUB_STORAGE_S3_ACCESS_KEY
LEGACYHUB_STORAGE_S3_SECRET_KEY
LEGACYHUB_STORAGE_S3_BUCKET

QDRANT_HOST
QDRANT_GRPC_PORT
QDRANT_COLLECTION

OLLAMA_BASE_URL
CHISTA_AI_DEFAULT_MODEL
CHISTA_EMBEDDING_MODEL

JIRA_BASE_URL
JIRA_EMAIL
JIRA_API_TOKEN

CONFLUENCE_BASE_URL
CONFLUENCE_EMAIL
CONFLUENCE_API_TOKEN

GITHUB_TOKEN

Secrets must be supplied at runtime and must not be stored in the image.

⁠Persistence

The backend container itself should remain replaceable.

Persistent data is held by external infrastructure:

PostgreSQL
Neo4j
SeaweedFS
Qdrant

These services require persistent storage for non-temporary environments.

⁠Health

Spring Boot Actuator exposes the application health endpoint:

/actuator/health

⁠Image Tags

⁠latest

lipad/chista-backend:latest

⁠Commit-specific

lipad/chista-backend:sha-<commit-sha>

Commit-specific tags are preferred for reproducible deployments.

⁠CI

Backend CI currently:

Maven verify
→ Docker image build

Tests run with supporting CI services such as:

PostgreSQL
Neo4j
S3Mock
Qdrant

On main, the image can be published to Docker Hub.

⁠Deployment Direction

Current:

Docker Compose

Planned:

Helm
Kubernetes
ArgoCD

The same backend image should be reusable in all environments.