Skip to content

Commit 797c280

Browse files
imbajinimbajin
committed
doc: add AGENTS.md, update README and project config
Add AGENTS.md with guidance for AI coding assistants and repository build/run commands. Expand and reorganize README: add architecture diagrams, detailed module overviews, quick start, Docker examples, build/test commands, and bump example dependency versions to 1.7.0. Update .serena/project.yml to include project_name and placeholder settings for included tools, modes, and fixed_tools to better configure Serena project metadata.
1 parent f58194b commit 797c280

File tree

3 files changed

+564
-47
lines changed

3 files changed

+564
-47
lines changed

‎.serena/project.yml‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,27 @@ excluded_tools: []
7979
# initial prompt for the project. It will always be given to the LLM upon activating the project
8080
# (contrary to the memories, which are loaded on demand).
8181
initial_prompt: ""
82-
82+
# the name by which the project can be referenced within Serena
8383
project_name: "toolchain"
84+
85+
# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
8486
included_optional_tools: []
87+
88+
# list of mode names to that are always to be included in the set of active modes
89+
# The full set of modes to be activated is base_modes + default_modes.
90+
# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
91+
# Otherwise, this setting overrides the global configuration.
92+
# Set this to [] to disable base modes for this project.
93+
# Set this to a list of mode names to always include the respective modes for this project.
94+
base_modes:
95+
96+
# list of mode names that are to be activated by default.
97+
# The full set of modes to be activated is base_modes + default_modes.
98+
# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
99+
# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
100+
# This setting can, in turn, be overridden by CLI parameters (--mode).
101+
default_modes:
102+
103+
# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
104+
# This cannot be combined with non-empty excluded_tools or included_optional_tools.
105+
fixed_tools: []

‎AGENTS.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Apache HugeGraph Toolchain - a multi-module Maven project providing utilities for the HugeGraph graph database. Current version: 1.7.0.
8+
9+
## Build Commands
10+
11+
### Full Build
12+
```bash
13+
mvn clean install -DskipTests -Dmaven.javadoc.skip=true -ntp
14+
```
15+
16+
### Module-Specific Builds
17+
18+
**Java Client:**
19+
```bash
20+
mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp
21+
```
22+
23+
**Loader (requires client):**
24+
```bash
25+
mvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp
26+
```
27+
28+
**Hubble (requires client + loader):**
29+
```bash
30+
mvn install -pl hugegraph-client,hugegraph-loader -am -DskipTests -ntp
31+
cd hugegraph-hubble && mvn package -DskipTests -ntp
32+
```
33+
34+
**Tools:**
35+
```bash
36+
mvn install -pl hugegraph-client,hugegraph-tools -am -DskipTests -ntp
37+
```
38+
39+
**Spark Connector:**
40+
```bash
41+
mvn install -pl hugegraph-client,hugegraph-spark-connector -am -DskipTests -ntp
42+
```
43+
44+
**Go Client:**
45+
```bash
46+
cd hugegraph-client-go && make all
47+
```
48+
49+
## Testing
50+
51+
### Client Tests
52+
```bash
53+
cd hugegraph-client
54+
mvn test -Dtest=UnitTestSuite # Unit tests (no server required)
55+
mvn test -Dtest=ApiTestSuite # API tests (requires HugeGraph server)
56+
mvn test -Dtest=FuncTestSuite # Functional tests (requires HugeGraph server)
57+
```
58+
59+
### Loader Tests (profiles)
60+
```bash
61+
cd hugegraph-loader
62+
mvn test -P unit # Unit tests
63+
mvn test -P file # File source tests
64+
mvn test -P hdfs # HDFS tests (requires Hadoop)
65+
mvn test -P jdbc # JDBC tests (requires MySQL)
66+
mvn test -P kafka # Kafka tests
67+
```
68+
69+
### Hubble Tests
70+
```bash
71+
mvn test -P unit-test -pl hugegraph-hubble/hubble-be -ntp
72+
```
73+
74+
### Tools Tests
75+
```bash
76+
mvn test -Dtest=FuncTestSuite -pl hugegraph-tools -ntp
77+
```
78+
79+
## Code Style
80+
81+
Checkstyle enforced via `tools/checkstyle.xml`:
82+
- Max line length: 100 characters
83+
- 4-space indentation (no tabs)
84+
- No star imports
85+
- No `System.out.println`
86+
87+
Run checkstyle:
88+
```bash
89+
mvn checkstyle:check
90+
```
91+
92+
## Architecture
93+
94+
### Module Dependencies
95+
```
96+
hugegraph-loader, hugegraph-tools, hugegraph-hubble, hugegraph-spark-connector
97+
↓
98+
hugegraph-client
99+
↓
100+
hugegraph-common (external)
101+
```
102+
103+
### Key Patterns
104+
105+
**hugegraph-client** - Manager/Facade pattern:
106+
- `HugeClient` is the entry point providing access to specialized managers
107+
- `SchemaManager`, `GraphManager`, `GremlinManager`, `TraverserManager`, etc.
108+
- Builder pattern for fluent schema creation
109+
110+
**hugegraph-loader** - Pipeline with Factory pattern:
111+
- `InputSource` interface with implementations: `FileSource`, `HDFSSource`, `JDBCSource`, `KafkaSource`, `GraphSource`
112+
- `InputReader.create()` factory method creates appropriate reader for source type
113+
114+
**hugegraph-hubble** - Spring Boot MVC:
115+
- Backend: `controller/` → `service/` → `mapper/` layers
116+
- Frontend: React + TypeScript + MobX + Ant Design
117+
- H2 database for metadata storage
118+
119+
**hugegraph-tools** - Command pattern:
120+
- Manager classes for operations: `BackupManager`, `RestoreManager`, `GraphsManager`
121+
122+
### Key Directories
123+
124+
| Module | Main Code | Package |
125+
|--------|-----------|---------|
126+
| client | `hugegraph-client/src/main/java` | `org.apache.hugegraph` |
127+
| loader | `hugegraph-loader/src/main/java` | `org.apache.hugegraph.loader` |
128+
| hubble-be | `hugegraph-hubble/hubble-be/src/main/java` | `org.apache.hugegraph` |
129+
| hubble-fe | `hugegraph-hubble/hubble-fe/src` | React/TypeScript |
130+
| tools | `hugegraph-tools/src/main/java` | `org.apache.hugegraph` |
131+
| spark | `hugegraph-spark-connector/src/main/scala` | `org.apache.hugegraph.spark` |
132+
133+
## Running Applications
134+
135+
### Hubble (Web UI on port 8088)
136+
```bash
137+
cd hugegraph-hubble/apache-hugegraph-hubble-incubating-*/bin
138+
./start-hubble.sh # Background
139+
./start-hubble.sh -f # Foreground
140+
./stop-hubble.sh # Stop
141+
```
142+
143+
### Loader
144+
```bash
145+
cd hugegraph-loader/apache-hugegraph-loader-incubating-*
146+
./bin/hugegraph-loader.sh [options]
147+
```
148+
149+
## Docker
150+
151+
```bash
152+
# Loader
153+
cd hugegraph-loader && docker build -t hugegraph/hugegraph-loader:latest .
154+
155+
# Hubble
156+
cd hugegraph-hubble && docker build -t hugegraph/hugegraph-hubble:latest .
157+
```

0 commit comments

Comments
 (0)