docs: add comprehensive documentation for the LexBuild monorepo - #60
Merged
Conversation
- Architecture - Packages - Apps - Development - Reference
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a comprehensive documentation set under docs/ for the LexBuild monorepo, covering architecture, package/app responsibilities, development workflows, and reference specifications intended to describe (and in some places normatively specify) LexBuild’s inputs/outputs.
Changes:
- Introduces structured architecture/development/package/app documentation pages under
docs/. - Adds reference specifications for USLM elements and LexBuild output format (frontmatter + sidecars).
- Adds CLI/reference material intended to standardize usage and expected outputs.
Reviewed changes
Copilot reviewed 25 out of 25 changed files in this pull request and generated 19 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/README.md | Top-level documentation index linking to architecture/development/packages/apps/reference sections. |
| docs/apps/astro.md | Describes the Astro app setup, dev/build commands, and content workflow. |
| docs/architecture/overview.md | High-level architecture overview and component boundaries. |
| docs/architecture/monorepo-structure.md | Monorepo layout and package/app roles. |
| docs/architecture/build-pipeline.md | Turborepo/task pipeline documentation and common build/dev commands. |
| docs/architecture/conversion-pipeline.md | End-to-end conversion flow (download → parse/build AST → render → write outputs). |
| docs/architecture/ast-model.md | LexBuild AST model description and node responsibilities. |
| docs/architecture/link-resolution.md | Cross-reference/link resolution behavior across USC/eCFR and fallbacks. |
| docs/architecture/performance.md | Performance guidance and operational considerations. |
| docs/development/getting-started.md | Local dev prerequisites and common workflows. |
| docs/development/testing.md | Test strategy and how to run tests in the monorepo. |
| docs/development/coding-standards.md | TypeScript/repo coding standards and conventions. |
| docs/development/debugging.md | Debugging approaches and tips for converters/apps. |
| docs/development/extending.md | Guidance for adding features/packages and extending pipelines. |
| docs/development/ci-cd.md | CI/CD documentation and checks expected in automation. |
| docs/development/release-process.md | Release/versioning process documentation. |
| docs/packages/core.md | @lexbuild/core package responsibilities and APIs. |
| docs/packages/usc.md | @lexbuild/usc responsibilities and USC-specific conversion details. |
| docs/packages/ecfr.md | @lexbuild/ecfr responsibilities and eCFR-specific conversion details. |
| docs/packages/cli.md | @lexbuild/cli command surface and how it ties packages together. |
| docs/reference/cli-reference.md | CLI command/flag reference and examples. |
| docs/reference/output-format.md | “Authoritative” spec for output directory layout, frontmatter, and sidecars. |
| docs/reference/uslm-element-reference.md | USLM (USC XML) element catalog and mapping to AST/Markdown. |
| docs/reference/ecfr-element-reference.md | eCFR element/identifier reference and mapping notes. |
| docs/reference/glossary.md | Shared terminology definitions used across the documentation set. |
|
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
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 pull request adds comprehensive documentation for the LexBuild project, including an overview of the platform, its architecture, the web application, and a detailed explanation of the internal AST (Abstract Syntax Tree) model. The documentation is organized to help developers understand the system's design, content pipeline, and extensibility.
Some of the most important changes are:
Project Overview and Structure:
README.mdthat provides a high-level overview of LexBuild, its purpose, major features, architectural organization, and links to detailed documentation for each package and component.Web Application Documentation:
docs/apps/astro.md, an in-depth guide to the Astro-based web application, covering its architecture, tech stack, routing, content serving, sidebar navigation, search integration, dark mode implementation, styling, development workflow, environment variables, directory structure, SEO strategies, and key design decisions.AST Model and Rendering Pipeline:
docs/architecture/ast-model.md, a detailed specification of the LexBuild AST, including node types, transformation process from XML to Markdown, type definitions, rendering logic, and frontmatter metadata structure. This documentation explains how legal XML is normalized and rendered, supporting both U.S. Code and eCFR sources.