Skip to content

CLAUDE.md

Latest commit

 

History

History
197 lines (145 loc) · 7.99 KB

CLAUDE.md

File metadata and controls

197 lines (145 loc) · 7.99 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This project will examine how to provide polycentric knowledge processing by orchestrating multiple monocentric instances of knowledge processing systems via a holonic overlay. Being polycentric is differentiated from being distributed by polycentricity's focus on orchestration over heterogenous instances each having their own "center" whereas distribution leans more to orchestration over homogenous instances and a merging or blurring of centers. The goal of this project is to develop a POC of polycentric knowledge processing derived from two individual instances of the Flexo MMS (Model Management System). Flexo is being used as a exemplar of an operational knowledge processing system used by Engineers to develop and operate high reliability systems.

At a future point in time, a second POC using Discourse Graphs may be developed as a sister POC with Discourse Graphs being the exemplar of research knowledge processing system used by Scientists to extend knowledge.

Flexo Overview

This is a deployment configuration repository for Flexo MMS (Model Management System) - a version control system for RDF-based model data. It is NOT a source code repository; it orchestrates deployment of multiple microservices via Docker Compose and Kubernetes.

Important: Flexo MMS supports native RDF data and is distinct from Exec MMS (which supports JSON documents).

Common Commands

Two-Instance Setup (Polycentric POC)

# Start Instance A
docker-compose -f instances/instance-a/docker-compose.yml up -d

# Start Instance B
docker-compose -f instances/instance-b/docker-compose.yml up -d

# Start both instances
docker-compose -f instances/instance-a/docker-compose.yml up -d && docker-compose -f instances/instance-b/docker-compose.yml up -d

# Shutdown both instances
docker-compose -f instances/instance-a/docker-compose.yml down && docker-compose -f instances/instance-b/docker-compose.yml down

API Authentication

# Instance A: Get JWT token (use user01/password1 or user02/password2)
curl -u user01 -X GET http://localhost:8082/login
# Use token for Layer1 API at http://localhost:8080

# Instance B: Get JWT token
curl -u user01 -X GET http://localhost:8182/login
# Use token for Layer1 API at http://localhost:8180

Single Instance (Original Flexo Deployment)

# Start with Fuseki backend (default)
docker-compose -f flexo-mms-deployment/docker-compose/docker-compose.yml up

# Shutdown
docker-compose -f flexo-mms-deployment/docker-compose/docker-compose.yml down

Architecture

Port Allocation (Two-Instance Setup)

Service Instance A Instance B Purpose
Layer1 Service 8080 8180 Main API for model management, RDF handling
Store Service 8081 8181 Artifact/blob storage (S3-compatible)
Auth Service 8082 8182 Authentication, JWT token generation
Apache Fuseki 3030 3130 Quad store (SPARQL endpoint)
MinIO 9000 9100 S3-compatible object storage
OpenLDAP 1389 1489 User/group management

Network Isolation

  • Instance A: flexo-mms-instance-a-network
  • Instance B: flexo-mms-instance-b-network

Service Dependencies

Layer1 Service → Store Service, Auth Service, Quad Store
Auth Service → OpenLDAP, Quad Store
Store Service → MinIO

Directory Structure

  • instances/ - Two isolated Flexo MMS instances for polycentric POC
    • instance-a/ and instance-b/ - Each contains:
      • docker-compose.yml - Instance-specific Docker Compose config
      • env/ - Environment files with instance-specific hostnames
      • mount/cluster.trig - Initial RDF data with instance-specific URIs
  • flexo-mms-deployment/ - Original Flexo MMS deployment repo (reference)
    • docker-compose/ - Single-instance Docker Compose configurations
    • k8s/ - Kubernetes manifests

GraphDB Setup (if using GraphDB backend)

  1. Access UI at http://localhost:7200
  2. Create repository: Setup > Repositories > Create > GraphDB Repository
    • Repository ID: openmbee
    • Ruleset: "No inference"
    • Enable: content index, predicate list index, FTS index
  3. Import data: Import > Upload RDF Files > select mount/cluster.trig

Resources

Project Plan

Step 1 - COMPLETE

As it currently stands, this project contains a clone of the Flexo MMS Deployment repo. Review this repo and create a plan for instantiating two independent instances of Flexo MMS on this computer.

Status: Implemented. The instances/ directory contains two fully isolated Flexo MMS configurations (instance-a and instance-b) ready to run.

Plan: Two Isolated Flexo MMS Instances

Approach: Create two separate docker-compose configurations, each with distinct ports, container names, and networks. This provides complete isolation between instances while keeping configurations explicit and independently modifiable.

Directory Structure:

distributed-knowledge-processing/
├── instances/
│   ├── instance-a/
│   │   ├── docker-compose.yml
│   │   ├── env/                    # Copied and modified from original
│   │   └── mount/
│   │       └── cluster.trig        # Initial RDF data
│   └── instance-b/
│       ├── docker-compose.yml
│       ├── env/
│       └── mount/
│           └── cluster.trig
└── flexo-mms-deployment/           # Original repo (reference)

Port Allocation:

Service Instance A Instance B
Layer1 Service 8080 8180
Store Service 8081 8181
Auth Service 8082 8182
Apache Fuseki 3030 3130
MinIO 9000 9100
OpenLDAP 1389 1489

Network Isolation:

  • Instance A: flexo-mms-instance-a-network
  • Instance B: flexo-mms-instance-b-network

Container Naming Convention:

  • Instance A: instance-a-<service> (e.g., instance-a-layer1-service)
  • Instance B: instance-b-<service> (e.g., instance-b-layer1-service)

Implementation Steps:

  1. Create instances/ directory structure
  2. Copy docker-compose.yml to each instance directory
  3. Modify each docker-compose.yml:
    • Update all container_name values with instance prefix
    • Update all hostname values with instance prefix
    • Update port mappings per the allocation table above
    • Update network name to instance-specific network
    • Update volume mount paths to local ./mount and ./env
  4. Copy env/ directory to each instance and update internal service hostnames (e.g., auth-service → instance-a-auth-service)
  5. Copy mount/cluster.trig to each instance

Commands After Implementation:

# Start Instance A
docker-compose -f instances/instance-a/docker-compose.yml up -d

# Start Instance B
docker-compose -f instances/instance-b/docker-compose.yml up -d

# Instance A API
curl -u user01 -X GET http://localhost:8082/login  # Auth
# Use token for http://localhost:8080              # Layer1

# Instance B API
curl -u user01 -X GET http://localhost:8182/login  # Auth
# Use token for http://localhost:8180              # Layer1

# Shutdown
docker-compose -f instances/instance-a/docker-compose.yml down
docker-compose -f instances/instance-b/docker-compose.yml down

Verification Criteria:

  • Both instances start without port conflicts
  • Each instance has isolated data (changes in A don't appear in B)
  • Authentication works independently on each instance
  • API calls to each instance return independent results