Hive

Experimental GraphQL backend for structured computational argumentation.

Hive is a university Praxisprojekt developed at TH Köln. It explored how argumentative discourse can be represented and manipulated as structured graph data, and preceded the later Argument Networks Bachelor thesis.

The repository is a Python backend prototype: FastAPI hosts a Strawberry GraphQL API, service classes coordinate domain behavior, repositories isolate most Neo4j access, and neomodel maps the argument graph to Neo4j.

What is implemented

• A GraphQL API for users, townsquares, questions, claims, premises, and evidence
• Neo4j persistence through asynchronous neomodel models and repositories
• JWT login, bcrypt password hashing, authenticated domain queries, and ownership checks on mutations
• Graph relationships for asking and answering questions, supporting or countering claims, attaching premises, and supporting or countering premises with evidence
• Query-depth, alias-count, and token-count limits on GraphQL operations
• Layered controller, service, repository, and persistence responsibilities

The implementation is an academic prototype rather than a production service. It does not contain a user interface, argument-mining pipeline, embedding or semantic-search system, vector database, recommendation engine, or graph-analytics implementation. Those ideas appeared as planned work in earlier documentation or belong to later projects in the same research trajectory.

Architecture

flowchart TD
    Client[GraphQL client] --> FastAPI[FastAPI /graphql]
    FastAPI --> Controllers[Strawberry resolvers / controllers]
    Controllers --> Services[Domain services]
    Services --> Repositories[Repositories]
    Repositories --> Neomodel[neomodel]
    Neomodel --> Neo4j[(Neo4j)]

    Client -. Bearer token .-> Context[GraphQL authentication context]
    Context --> Auth[JWT authentication service]
    Controllers --> Context

Loading

Controllers translate GraphQL inputs and outputs. Services coordinate use cases such as creating a claim with an author and its graph relationships. Repositories perform node lookup, persistence, relationship access, and constraint-related database operations. This is best described as a layered architecture with service/repository patterns: some neomodel transaction and node concepts remain visible in services, so the code does not claim strict Clean Architecture boundaries.

The GraphQL schema explicitly composes the domain controllers in src/app. Authentication is supplied through Strawberry's request context and enforced at each domain boundary. Registration and login are public; domain queries and mutations require a bearer token, and updates or deletions verify authorship or townsquare ownership. Expected application errors receive stable GraphQL error codes without leaking unexpected exception details.

Domain model

The graph models discourse as addressable, connected entities rather than flat posts:

flowchart LR
    User -- MEMBER_OF --> Townsquare
    Townsquare -- CREATED_BY --> User
    Question -- ASKED_BY --> User
    Question -- ASKED_IN --> Townsquare
    Question -- QUESTIONS --> Claim
    Claim -- AUTHORED_BY --> User
    Claim -- ANSWERS --> Question
    Claim -- SUPPORTS / ATTACKS --> Claim
    Claim -- HAS_PREMISE --> Premise
    Premise -- AUTHORED_BY --> User
    Evidence -- AUTHORED_BY --> User
    Evidence -- SUPPORTS / COUNTERS --> Premise

Loading

• Townsquares group members and questions around a discourse space.
• Questions can be asked in a townsquare or address an existing claim.
• Claims can answer questions and support or attack other claims.
• Premises provide reasoning attached to one or more claims.
• Evidence records content and a source string, then supports or counters premises.
• Users author argument entities and join townsquares.

This model is intentionally exploratory. For example, an evidence source is currently a string rather than a separately modeled source node.

Technology

• Python 3.12
• FastAPI and Uvicorn
• Strawberry GraphQL
• Neo4j 5.x, neomodel, and the Neo4j Python driver
• JSON Web Tokens via python-jose
• Password hashing via bcrypt
• pytest
• Docker and Docker Compose

Repository structure

src/
├── app/
│   ├── arg_framework/   # Claims, questions, premises, evidence
│   ├── auth/            # JWT service and GraphQL request context
│   ├── townsquare/      # Discourse-space domain component
│   └── user/            # User model and use cases
├── core/                    # FastAPI startup, configuration, schema assembly
└── infra/db/                # Shared repository contracts and graph utilities
scripts/                   # Idempotent local demo-data seed
examples/                  # Verified GraphQL workflow
tests/                     # Unit and Neo4j integration tests

Domain folders generally contain a neomodel model, GraphQL controller and schema, service, and repository.

Run with Docker

Docker Compose is the shortest reproducible path. It builds the API, starts Neo4j 5.26 LTS with persistent named volumes, waits for the database health check, and then starts the API:

docker compose up --build -d
docker compose ps

Open:

• GraphiQL: http://localhost:8000/graphql
• API readiness: http://localhost:8000/health/ready
• Neo4j Browser: http://localhost:7474

The local defaults are neo4j / hive-development for Neo4j. Override NEO4J_PASSWORD and SECRET_KEY in your shell or .env before starting Compose when the defaults are unsuitable.

Load an idempotent example argument graph:

docker compose run --rm api python -m scripts.seed_demo

The seed creates the local demo login demo / demo-password. Stop the stack with docker compose down. Add --volumes only when you intentionally want to delete the persisted local graph.

Run directly

Prerequisites

• Python 3.12
• A reachable Neo4j 5.x instance with a database named neo4j

The application does not provision Neo4j. Start a local Neo4j instance or create a Neo4j Aura database before launching the API.

Setup

git clone https://github.com/Voidcake/Hive.git
cd Hive

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt

cp .env.example .env

Edit .env with your Neo4j connection details and a development JWT secret. NEO4J_URI must be in host:port form because the application constructs the full Bolt URL.

NEO4J_URI=localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j
SECRET_KEY=replace-with-a-random-secret
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

You can generate a local secret with openssl rand -hex 32.

Start the API from the repository root:

python -m uvicorn src.core.main:app --reload

Then open GraphiQL at http://127.0.0.1:8000/graphql. Startup configures neomodel and checks the Neo4j connection; startup fails if the database is unavailable.

GraphQL example

Registration and login are public. Send the token returned by auth.login as an Authorization: Bearer <token> header for all domain operations. A complete registration, login, and argument traversal example is available in examples/argument_workflow.graphql.

The seeded graph can be traversed with:

query ArgumentGraph {
  question {
    allQuestions {
      question
      answeredBy {
        content
        premises {
          content
          evidence { content source }
        }
      }
    }
  }
}

Tests

The default suite runs database-independent unit and boundary tests:

python -m pytest

Run the disposable Neo4j integration test through Compose:

docker compose --profile test run --rm integration-tests

GitHub Actions runs compilation, unit tests, the Neo4j integration workflow, and a production-container build for every pull request and push to main.

Project status

Hive is a preserved and hardened experimental academic prototype. It demonstrates Python backend structure and non-trivial graph-domain modeling, but it is not actively operated and should not be read as a claim of production readiness, scalability, or production-grade security.

License

Hive is available under the MIT License.