Update README.md to provide a comprehensive overview of The Order monorepo, including repository structure, quickstart guide, development workflow, and contribution guidelines.

2025-11-07 22:34:54 -08:00
parent e020318829
commit 4af7580f7a
128 changed files with 4558 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,181 @@
-# the-order-monorepo
-# the-order-monorepo
+# The Order
+
+Monorepo for The Order - A comprehensive platform for legal, financial, and governance systems.
+
+## Overview
+
+The Order is a mono-repo containing all applications, services, packages, infrastructure, and documentation for managing legal documents, financial systems, identity management, datarooms, and member portals.
+
+## Repository Structure
+
+```
+the-order/
+├─ apps/                        # End-user applications (web + portals)
+│  ├─ portal-public/            # Public web presence
+│  ├─ portal-internal/          # Internal web (admin/ops)
+│  ├─ mcp-members/              # MCP for Members of The Order
+│  └─ mcp-legal/                # MCP for Legal Purpose (matters, filings, attestations)
+│
+├─ services/                    # Domain services (APIs, workers)
+│  ├─ intake/                   # "Drop content" tool: ingestion → OCR → classify → route
+│  ├─ identity/                 # Digital Systems (eIDAS/DID, verifiable credentials)
+│  ├─ finance/                  # Requisite financial systems (payments, ledgers, rates)
+│  ├─ dataroom/                 # Dataroom(s) for all deals (secure VDR, deal room APIs)
+│  ├─ omnis-brand/              # Branded version of OMNIS (as a service/app shell)
+│  └─ arromis-brand/            # Branded version of ARROMIS (as a service/app shell)
+│
+├─ packages/                    # Shared libraries (versioned in the mono-repo)
+│  ├─ ui/                       # Design system (React/Tailwind components)
+│  ├─ schemas/                  # Zod/OpenAPI/JSON Schema contracts
+│  ├─ auth/                     # AuthZ/AuthN helpers (OIDC, wallet, eIDAS adapters)
+│  ├─ storage/                  # S3/GCS abstraction, object lifecycle, WORM mode
+│  ├─ crypto/                   # KMS/HSM client, key mgmt, signatures (eIDAS/DID)
+│  ├─ workflows/                # Temporal/Step Functions definitions
+│  └─ test-utils/               # Testing utilities and helpers
+│
+├─ infra/                       # Everything-as-code
+│  ├─ terraform/                # Cloud infra, secrets backends, KMS/HSM, PKI
+│  ├─ k8s/                      # Helm charts/overlays (dev/stage/prod)
+│  ├─ gateways/                 # API gateway / proxy / WAF configs
+│  └─ cicd/                     # Reusable CI templates, SBOM, signing
+│
+├─ docs/                        # Living documentation
+│  ├─ legal/                    # Generated legal/treaty artifacts, policies
+│  ├─ governance/               # Contribution, security, incident runbooks
+│  ├─ architecture/             # ADRs, data flows, threat models
+│  └─ product/                  # Roadmaps, PRDs
+│
+└─ scripts/                     # Utility scripts
+```
+
+## Quickstart
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- pnpm >= 8.0.0
+- Git
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/the-order/the-order.git
+cd the-order
+
+# Initialize submodules (if any)
+git submodule update --init --recursive
+
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+```
+
+### Development
+
+```bash
+# Start all apps and services in development mode
+pnpm dev
+
+# Run specific workspace
+pnpm --filter portal-public dev
+
+# Run linting
+pnpm lint
+
+# Run type checking
+pnpm type-check
+
+# Run tests
+pnpm test
+```
+
+### Environment Variables
+
+Environment variables are managed using SOPS (Secrets Operations). See `docs/governance/SECURITY.md` for details.
+
+1. Copy `.env.example` files to `.env.local` in each workspace
+2. For encrypted secrets, use SOPS with age keys
+3. Never commit plaintext secrets to the repository
+
+Example:
+```bash
+# Decrypt and load secrets
+sops -d secrets/dev.env.enc > .env.local
+```
+
+## Environments
+
+- **dev**: Local development environment
+- **stage**: Staging environment for testing
+- **prod**: Production environment
+
+Environment-specific configurations are in `infra/k8s/overlays/`.
+
+## Git Submodules
+
+Some services and apps are managed as Git submodules. To add submodules:
+
+```bash
+# See scripts/add-submodules.sh for examples
+./scripts/add-submodules.sh
+```
+
+To update submodules:
+```bash
+git submodule update --remote
+```
+
+## Contribution
+
+Please read [CONTRIBUTING.md](docs/governance/CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+### Development Workflow
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Run tests and linting: `pnpm test && pnpm lint`
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/)
+5. Push and create a Pull Request
+
+### Code Standards
+
+- TypeScript strict mode enabled
+- ESLint + Prettier for code formatting
+- All tests must pass
+- Type checking must pass
+- Follow the architecture decisions in `docs/architecture/adrs/`
+
+## Security
+
+See [SECURITY.md](docs/governance/SECURITY.md) for security policies and reporting procedures.
+
+## Architecture
+
+Architecture Decision Records (ADRs) are located in `docs/architecture/adrs/`. See [docs/architecture/README.md](docs/architecture/README.md) for more information.
+
+## Release Process
+
+Releases are managed via semantic versioning and automated through CI/CD:
+
+1. Merge to `main` triggers automated tests and builds
+2. Tagged releases trigger deployment to staging
+3. Manual approval required for production deployment
+4. See `.github/workflows/release.yml` for details
+
+## License
+
+See [LICENSE](LICENSE) for license information.
+
+## Support
+
+For questions and support, please open an issue in this repository.
+
+## Related Documentation
+
+- [Security Policy](docs/governance/SECURITY.md)
+- [Contributing Guide](docs/governance/CONTRIBUTING.md)
+- [Architecture Documentation](docs/architecture/README.md)
+- [Product Roadmap](docs/product/README.md)