Skip to content

Commit 140ab0d

Browse files
DovOpsCopilot
DovOps
and
Copilot
authored
Documentation restructure and initial AGENTS.md (#327)
* feat: restructure docs and add agentic AI support Documentation improvements: - Add Mermaid diagram rendering to Docusaurus - Add remark plugin for GitHub link transformation in docs - Create Build & Run guide (docs/running.md), slim down README - Replace team page with project-history page - Add proper frontmatter to all doc files - Update roadmap with 2026 goals and agentic exercises C4 diagrams: - Rename c4-diagram.dsl to workspace.dsl (Structurizr Lite standard) - Add autoLayout to all views - Add GitHub Action to auto-render PNG diagrams on DSL changes - Add rendered diagrams to overview page Agentic AI: - Update AGENTS.md with documentation guidance - Add diagram sync rules (C4, Mermaid, component table) - Add project history update guidelines * fixing bad references Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Updates based on copilot feedback * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Fix GHA for rendering C4 diagrams * Updated openapi to be dynamically generateable and to use JSON. * docs: smarter relative link transform (blob vs tree, preserve fragments) * docs: fix edit links and allow DOCS_BRANCH override --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 2e0c232 commit 140ab0d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1927
-906
lines changed

‎.github/workflows/generate-openapi.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Generate OpenAPI Specs
2+
3+
on:
4+
workflow_dispatch:
5+
6+
jobs:
7+
generate:
8+
runs-on: ubuntu-latest
9+
permissions:
10+
contents: write
11+
12+
steps:
13+
- name: Checkout repository
14+
uses: actions/checkout@v4
15+
with:
16+
token: ${{ secrets.GITHUB_TOKEN }}
17+
18+
- name: Generate OpenAPI specs
19+
run: scripts/generate-openapi.sh --start-compose
20+
21+
- name: Commit generated specs
22+
run: |
23+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
24+
git config --local user.name "github-actions[bot]"
25+
git add **/openapi.json
26+
git diff --staged --quiet || git commit -m "chore: refresh OpenAPI specs"
27+
git push

‎.github/workflows/render-c4-diagrams.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Render C4 Diagrams
2+
3+
on:
4+
push:
5+
paths:
6+
- 'docs/c4/workspace.dsl'
7+
branches:
8+
- main
9+
pull_request:
10+
paths:
11+
- 'docs/c4/workspace.dsl'
12+
workflow_dispatch: # Allow manual trigger
13+
14+
jobs:
15+
render:
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: write
19+
20+
steps:
21+
- name: Checkout repository
22+
uses: actions/checkout@v4
23+
with:
24+
token: ${{ secrets.GITHUB_TOKEN }}
25+
26+
- name: Set up Java
27+
uses: actions/setup-java@v4
28+
with:
29+
distribution: 'temurin'
30+
java-version: '17'
31+
32+
- name: Install Graphviz
33+
run: |
34+
sudo apt-get update
35+
sudo apt-get install -y graphviz
36+
37+
- name: Render C4 diagrams
38+
run: |
39+
# Download Structurizr CLI
40+
curl -L https://github.com/structurizr/cli/releases/download/v2024.07.03/structurizr-cli.zip -o structurizr-cli.zip
41+
unzip -o structurizr-cli.zip -d structurizr-cli
42+
43+
cd docs/c4
44+
45+
# Export to Graphviz DOT format (produces structurizr-{view-key}.dot files)
46+
../../structurizr-cli/structurizr.sh export -workspace workspace.dsl -format dot -output .
47+
48+
# Convert DOT to PNG using Graphviz with curved splines
49+
for dot_file in structurizr-*.dot; do
50+
output_name="${dot_file%.dot}.png"
51+
dot -Gsplines=curved -Tpng "$dot_file" -o "$output_name"
52+
done
53+
54+
# Clean up DOT files (keep only PNGs)
55+
rm -f *.dot
56+
57+
# List generated files
58+
echo "Generated files:"
59+
ls -la structurizr-*.png
60+
61+
- name: Commit rendered diagrams
62+
if: github.event_name == 'push'
63+
run: |
64+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
65+
git config --local user.name "github-actions[bot]"
66+
git add docs/c4/*.png
67+
git diff --staged --quiet || git commit -m "chore: auto-render C4 diagrams from workspace.dsl"
68+
git push

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ build/
88
# Excluding Local Build folder for company-specific building
99
.corp
1010

11+
# Structurizr Lite generated files
12+
docs/c4/workspace.json
13+
docs/c4/.structurizr
14+
1115
# Exclude package-lock to avoid company builds overriding standard locations
1216
package-lock.json
1317
yarn.lock

‎AGENTS.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# AGENTS.md
2+
3+
This repository is the FINOS TraderX sample trading application. It is intentionally simple, non-production, and designed for local experimentation across a distributed set of services.
4+
5+
## Start here (project context)
6+
- `README.md` for overall purpose and run modes.
7+
- `docs/running.md` for default ports, startup sequences, and environment variables.
8+
- `docs/README.md`, `docs/overview.md`, and `docs/flows.md` for architecture and sequence flows.
9+
- `docs/c4/workspace.dsl` for the C4 diagram source (use Structurizr Lite to render).
10+
11+
## Repository map (service roots)
12+
- `database/` (H2 database)
13+
- `reference-data/` (Node/NestJS reference data)
14+
- `trade-feed/` (Node/Socket.IO pub-sub)
15+
- `people-service/` (.NET)
16+
- `account-service/` (Java/Spring Boot)
17+
- `position-service/` (Java/Spring Boot)
18+
- `trade-service/` (Java/Spring Boot)
19+
- `trade-processor/` (Java/Spring Boot)
20+
- `web-front-end/` (Angular + React clients)
21+
- `docs/` and `website/` (documentation site)
22+
- `gitops/` and `ingress/` (K8s/Tilt and ingress config)
23+
24+
## Quick run options
25+
- Docker Compose (full system): from repo root, `docker compose up` (see `README.md`).
26+
- Kubernetes/Tilt: see `gitops/local/Tiltfile` and `docs/running.md` for `tilt up`.
27+
- Manual run: see `docs/running.md` for the recommended startup sequence and port env vars.
28+
29+
## Service-level guidance
30+
- Each service has a `README.md` with run details and prerequisites. Read that before editing.
31+
- OpenAPI specs are generated at runtime (Swagger) and saved as `*/openapi.json` when you run `scripts/generate-openapi.sh`. Swagger UI is typically exposed at `/swagger-ui.html` (or service-specific Swagger routes).
32+
- Java services use Gradle wrapper (`./gradlew`) from their service directory.
33+
- Node services use their local `package.json` scripts.
34+
- `web-front-end/` contains both Angular and React implementations; check each subfolder's README.
35+
36+
## When making changes
37+
- Prefer small, targeted edits in the service you are touching; do not refactor cross-service behavior unless requested.
38+
- If behavior or APIs change, refresh the OpenAPI specs via `scripts/generate-openapi.sh` and update any relevant docs in `docs/`.
39+
- Keep the non-production, demo nature of the project in mind.
40+
41+
## Keeping diagrams in sync
42+
When adding, removing, or changing services or their interactions, update **all** relevant diagrams:
43+
44+
1. **C4 diagram** (`docs/c4/workspace.dsl`) - The Structurizr DSL is the source of truth for architecture. PNG images are auto-rendered by GitHub Actions on push.
45+
2. **Mermaid diagrams** in `docs/overview.md` (simplified architecture) and `docs/flows.md` (sequence diagrams).
46+
3. **Component table** in `README.md` if adding/removing services.
47+
48+
The C4 DSL and Mermaid diagrams should stay consistent—if you update one, check if the other needs the same change.
49+
50+
## Documentation and website
51+
The project has two content surfaces that may overlap:
52+
1. **`docs/`** - Markdown files served by Docusaurus (architecture, flows, running instructions)
53+
2. **`website/src/components/`** - React components for the landing page (feature highlights, intro text)
54+
55+
**Avoid duplication**: The landing page is marketing-style (logo, tagline, feature cards, CTAs). The `docs/` folder is the reference material. If you add content, decide which surface it belongs to—don't put the same text in both places.
56+
57+
**Project history**: When making **major changes** (new services, architectural shifts, significant features), add an entry to `docs/project-history.md`. Minor fixes and routine maintenance do not need to be recorded.
58+
59+
**Relative links in docs**: Links like `../account-service` work on GitHub. The Docusaurus remark plugin (`website/src/remark/transformRelativeLinks.js`) converts them to full GitHub URLs at build time. Keep using relative links in `docs/` markdown files.
60+
61+
## Useful files by task
62+
- Architecture/flows: `docs/overview.md`, `docs/flows.md`, `docs/c4/workspace.dsl`
63+
- Local run and ports: `docs/running.md`
64+
- Docker/K8s: `docker-compose.yml`, `gitops/local/Tiltfile`
65+
- Front-end: `web-front-end/angular/README.md`, `web-front-end/react/README.md`
66+
- Docs site: `website/README.md`, `docs/`

0 commit comments

Comments
 (0)