Skip to content

Commit 220f938

Browse files
namedgraphnamedgraph
committed
README update
1 parent a2d1d71 commit 220f938

2 files changed

Lines changed: 117 additions & 4 deletions

File tree

‎CLAUDE.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
LinkedDataHub (LDH) is a low-code Knowledge Graph application platform that enables managing data, creating visualizations, and building apps on RDF Knowledge Graphs. It's a completely data-driven platform where applications and documents are defined as data, managed using a single generic HTTP API, and presented using declarative technologies.
8+
9+
## Build System and Development Commands
10+
11+
LinkedDataHub uses Maven as the primary build system with Docker for containerization.
12+
13+
### Development Setup
14+
```bash
15+
# Initial setup (requires .env file configuration)
16+
./bin/server-cert-gen.sh .env nginx ssl
17+
docker-compose up --build
18+
```
19+
20+
### Core Build Commands
21+
```bash
22+
# Maven build (Java 17 required)
23+
mvn clean install
24+
25+
# Build specific profiles
26+
mvn -Pstandalone clean install # Standalone WAR
27+
mvn -Pdependency clean install # JAR dependency
28+
mvn -Prelease clean install # Release with signing
29+
30+
# Docker-based development
31+
docker-compose up --build # Start all services
32+
docker-compose down -v # Stop and remove volumes
33+
sudo rm -rf data uploads && docker-compose down -v # Complete reset
34+
```
35+
36+
### Testing
37+
```bash
38+
# HTTP tests (requires running application)
39+
cd http-tests
40+
./run.sh ssl/owner/cert.pem [password] ssl/secretary/cert.pem [password]
41+
42+
# Test individual suites
43+
find ./document-hierarchy/ -name '*.sh' -exec bash {} \;
44+
```
45+
46+
## Architecture Overview
47+
48+
### Core Application Structure
49+
- **JAX-RS based**: Uses Jersey framework for RESTful web services
50+
- **Multi-application architecture**: Separate admin and end-user applications
51+
- **Data-driven design**: Applications and resources defined as RDF data
52+
- **XSLT-based UI**: Client-side rendering using Saxon-JS with XSLT transformations
53+
54+
### Key Components
55+
56+
#### Applications (`com.atomgraph.linkeddatahub.apps.model`)
57+
- `AdminApplication` - Administrative interface and functions
58+
- `EndUserApplication` - Main user-facing application
59+
- Applications are data-driven and loaded from RDF datasets
60+
61+
#### Security & Authentication (`com.atomgraph.linkeddatahub.server.filter.request.auth`)
62+
- WebID-based authentication with client certificates
63+
- OAuth2 integration (Google)
64+
- Authorization filters and context management
65+
- Multi-level security: Agent, Authorization, and Application filters
66+
67+
#### Data Management (`com.atomgraph.linkeddatahub.model`)
68+
- RDF-native data handling with Jena
69+
- Import/Export functionality for CSV, RDF, and other formats
70+
- SPARQL endpoint integration with separate admin and end-user stores
71+
72+
#### Resource Handling (`com.atomgraph.linkeddatahub.resource`)
73+
- RESTful resource endpoints for CRUD operations
74+
- File upload and content-addressed storage
75+
- Transformation and generation utilities
76+
77+
### Service Architecture
78+
The application runs as a multi-container setup:
79+
- **nginx**: Reverse proxy and SSL termination
80+
- **linkeddatahub**: Main Java application (Tomcat)
81+
- **fuseki-admin/fuseki-end-user**: Separate SPARQL stores
82+
- **varnish-frontend/varnish-admin/varnish-end-user**: Caching layers
83+
84+
### Data Flow
85+
1. Requests come through nginx proxy
86+
2. Varnish provides caching layer
87+
3. LinkedDataHub application handles business logic
88+
4. Data persisted to appropriate Fuseki triplestore
89+
5. XSLT transforms data for client presentation
90+
91+
### Key Extension Points
92+
- **Vocabulary definitions** in `com.atomgraph.linkeddatahub.vocabulary`
93+
- **Custom resource handlers** in `com.atomgraph.linkeddatahub.resource`
94+
- **Import processors** in `com.atomgraph.linkeddatahub.imports`
95+
- **XSLT transformations** in `src/main/webapp/static/com/atomgraph/linkeddatahub/xsl`
96+
97+
## CLI Tools
98+
LinkedDataHub includes extensive CLI tools in the `bin/` directory:
99+
- Resource management: `create-container.sh`, `create-item.sh`, `get.sh`, `post.sh`, `put.sh`
100+
- Import functionality: `imports/create-csv-import.sh`, `imports/import-rdf.sh`
101+
- Admin operations: `admin/model/add-class.sh`, `admin/acl/create-authorization.sh`
102+
- Certificate management: `webid-keygen.sh`, `server-cert-gen.sh`
103+
104+
Add CLI tools to PATH for development:
105+
```bash
106+
export PATH="$(find bin -type d -exec realpath {} \; | tr '\n' ':')$PATH"
107+
```
108+
109+
## Development Notes
110+
- Java 17 is required for compilation
111+
- The application uses AtomGraph's Processor and Web-Client libraries as core dependencies
112+
- XSLT stylesheets are processed during build to inline XML entities
113+
- Saxon-JS SEF files are generated during Maven package phase for client-side XSLT
114+
- WebID certificates are required for authenticated API access
115+
- The system expects Jena CLI tools to be available (`JENA_HOME` environment variable)

‎README.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -76,10 +76,7 @@ It takes a few clicks and filling out a form to install the product into your ow
7676
- `data` where the triplestore(s) will persist RDF data
7777
- `datasets` where LDH persists agent metadata files
7878
- `uploads` where LDH stores content-hashed file uploads
79-
It should take up to half a minute as datasets are being loaded into triplestores. After a successful startup, the last line of the Docker log should read something like:
80-
```
81-
linkeddatahub_1 | 09-Feb-2021 14:18:10.536 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [32609] milliseconds
82-
```
79+
It should take up to half a minute as datasets are being loaded into triplestores. After a successful startup you should see periodic healtcheck requests being made to the https://localhost:4443/ns URL.
8380
6. Install `ssl/owner/keystore.p12` into a web browser of your choice (password is the `owner_cert_password` secret value)
8481
- Google Chrome: `Settings > Advanced > Manage Certificates > Import...`
8582
- Mozilla Firefox: `Options > Privacy > Security > View Certificates... > Import...`
@@ -189,6 +186,7 @@ The scripts can be found in the [`bin`](https://github.com/AtomGraph/LinkedDataH
189186
```shell
190187
export PATH="$(find bin -type d -exec realpath {} \; | tr '\n' ':')$PATH"
191188
```
189+
If you will be using LinkedDataHub's CLI regurarly, add the above command to your shell profile.
192190

193191
_:warning: The CLI scripts internally use [Jena's CLI commands](https://jena.apache.org/documentation/tools/). Set up the Jena environment before running the scripts._
194192

0 commit comments

Comments
 (0)