Documentation restructure and initial AGENTS.md#327
Merged
Conversation
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
DovOps
requested review from
TheJuanAndOnly99,
bingenito,
Copilot,
mimiflynn,
psmulovics and
rocketstack-matt
✅ Deploy Preview for lucky-concha-f3599f ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Restructures and expands the project documentation for the Docusaurus site, adds initial agent guidance (AGENTS.md), and introduces automation/support for Mermaid + C4 diagram workflows.
Changes:
- Reorganized/expanded docs (new Build & Run guide, new Project History, updated Roadmap, updated home/overview/flows/code pages, updated sidebar/navigation)
- Added Mermaid support in Docusaurus and a remark plugin to convert repo-relative links to GitHub URLs at build time
- Renamed/updated Structurizr workspace and added a GitHub Action to render C4 PNGs
Reviewed changes
Copilot reviewed 17 out of 18 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| website/src/remark/transformRelativeLinks.js | New remark plugin to rewrite ../... links to GitHub URLs during site build |
| website/sidebars.js | Updates doc navigation order and replaces removed pages |
| website/package.json | Adds Mermaid theme dependency and unist-util-visit for the remark plugin |
| website/docusaurus.config.js | Enables Mermaid, wires in remark plugin, updates navbar/footer links and repo variables |
| docs/team.mdx | Removes obsolete Team page |
| docs/running.md | Adds consolidated Build & Run guide (Compose / K8s+Tilt / manual / corporate) |
| docs/roadmap.mdx | Replaces placeholder roadmap with 2026 goals and agentic exercises/prompts |
| docs/project-history.md | Adds project history and release notes page |
| docs/overview.md | Adds frontmatter, Mermaid overview diagram, and references to generated C4 PNGs |
| docs/home.mdx | Updates docs homepage with quick links and onboarding guidance |
| docs/flows.md | Updates frontmatter and adds a new Mermaid sequence diagram section |
| docs/code.md | Adds frontmatter and corrects/updates service map entries/links |
| docs/c4/workspace.dsl | Updates Structurizr views to use consistent autoLayout lr |
| docs/README.md | Refreshes docs folder README and pointers into the doc set |
| README.md | Slims root README and links to the full Build & Run guide |
| AGENTS.md | Adds initial guidance for coding agents and doc/diagram sync rules |
| .gitignore | Ignores Structurizr-generated files (workspace.json, .structurizr) |
| .github/workflows/render-c4-diagrams.yml | Adds workflow to render and commit C4 PNGs on DSL changes |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 17 out of 24 changed files in this pull request and generated 8 comments.
Comments suppressed due to low confidence (1)
docs/c4/workspace.dsl:69
- PR description mentions adding
autoLayout lr, but the updated DSL usesautoLayout tbfor all views. Either update the DSL to match the intended left-to-right layout, or update the PR description/docs to reflect top-to-bottom.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Contributor
Author
|
@karlmoll @maoo this is a finalized copy of the docs, and an agent file. This is ready to merge and it's only documentation. This should allow us to spin up http://traderx.finos.org as displayed in the preview app - https://deploy-preview-327--lucky-concha-f3599f.netlify.app/ |
Contributor
Author
|
In particular @karlmoll @psmulovics @rocketstack-matt take a look at roadmap doc which have some key info on next steps, etc. https://deploy-preview-327--lucky-concha-f3599f.netlify.app/docs/roadmap |
bingenito
approved these changes
Jan 26, 2026
devin-ai-integration bot
added a commit
to cognition-workshop/finos-traderX
that referenced
this pull request
Jan 28, 2026
- Remove 'Obviously' from reference-data/README.md for better tone - Pin actions/checkout to SHA hash for improved security Closes finos#328 Co-Authored-By: unknown <>
3 tasks
devin-ai-integration bot
added a commit
to cognition-workshop/finos-traderX
that referenced
this pull request
Jan 30, 2026
- Remove 'Obviously' from reference-data/README.md for better tone - Pin actions/checkout to SHA hash (v4.2.2) for improved security Closes finos#328 Co-Authored-By: unknown <>
5 tasks
devin-ai-integration bot
added a commit
to cognition-workshop/finos-traderX
that referenced
this pull request
Feb 5, 2026
- Fix typo 'containes' -> 'contains' in people-service/README.md - Remove stray backtick from heading in trade-service/README.md - Remove stray backtick from heading in reference-data/README.md - Replace 'Obviously' with more professional tone in reference-data/README.md - Capitalize 'Node.js' correctly in reference-data/README.md These changes improve documentation quality and address review feedback from PR finos#327 (issue finos#328). Co-Authored-By: unknown <>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
THIS SOFTWARE IS CONTRIBUTED SUBJECT TO THE TERMS OF THE FINOS Corporate Contributor License Agreement.
THIS SOFTWARE IS LICENSED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND ANY WARRANTY OF NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THIS SOFTWARE MAY BE REDISTRIBUTED TO OTHERS ONLY BY EFFECTIVELY USING THIS OR ANOTHER EQUIVALENT DISCLAIMER IN ADDITION TO ANY OTHER REQUIRED LICENSE TERMS.
Summary
This PR restructures the documentation, adds agentic AI support for coding agents, and improves the C4 diagram workflow.
Changes
📚 Documentation Restructure
docs/running.md) - Consolidated all run instructions (Docker Compose, Kubernetes/Tilt, manual, corporate environments)docs/project-history.md) - Tracks major milestones and releasesdocs/roadmap.mdx) - 2026 goals including progressive repo states, agentic exercises, and website launch🤖 Agentic AI Support
AGENTS.mdwith:🎨 Docusaurus Improvements
@docusaurus/theme-mermaidfor rendering architecture and sequence diagramswebsite/src/remark/transformRelativeLinks.js) converts relative links (e.g.,../account-service) to GitHub URLs at build time📐 C4 Diagrams
c4-diagram.dsltoworkspace.dsl- Structurizr Lite standard namingautoLayout lrto all views for consistent Graphviz rendering.github/workflows/render-c4-diagrams.yml) - Auto-renders PNG diagrams on DSL changes and commits them back.gitignore- Excludesworkspace.jsonand.structurizr(auto-generated)Files Changed
docs/home.mdx,docs/overview.md,docs/flows.md,docs/code.md,docs/running.md(new),docs/roadmap.mdx,docs/project-history.md(new)docs/c4/workspace.dsl(renamed),.github/workflows/render-c4-diagrams.yml(new)website/docusaurus.config.js,website/sidebars.js,website/package.json,website/src/remark/transformRelativeLinks.js(new)README.md,AGENTS.md,.gitignoredocs/team.mdx,docs/c4/c4-diagram.dslTesting
npm install && npm run start)