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

This commit is contained in:
defiQUG
2025-11-07 22:34:54 -08:00
parent e020318829
commit 4af7580f7a
128 changed files with 4558 additions and 2 deletions

236
docs/architecture/README.md Normal file
View File

@@ -0,0 +1,236 @@
# Architecture Documentation
This directory contains architecture documentation for The Order, including Architecture Decision Records (ADRs), data flow diagrams, and threat models.
## Architecture Decision Records (ADRs)
Architecture Decision Records document important architectural decisions made in the project. They capture the context, decision, and consequences of key choices.
### ADR Template
When creating a new ADR, use the template in `adrs/README.md`.
### Current ADRs
- See `adrs/` directory for all ADRs
- ADRs are numbered sequentially: `adr-001-*.md`, `adr-002-*.md`, etc.
### ADR Process
1. Propose an architectural decision
2. Create ADR using template
3. Discuss with team
4. Record decision in ADR
5. Update as needed if decision changes
## System Architecture
### High-Level Overview
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Portal │────▶│ Services │────▶│ Databases │
│ Apps │ │ (APIs) │ │ & Storage │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└───────────────────┴────────────────────┘
┌──────┴──────┐
│ Identity │
│ & Auth │
└─────────────┘
```
### Core Services
1. **Intake Service**: Document ingestion, OCR, classification
2. **Identity Service**: eIDAS/DID, verifiable credentials
3. **Finance Service**: Payments, ledgers, rate management
4. **Dataroom Service**: Secure VDR, deal rooms
5. **MCP Services**: Member and legal management portals
### Data Flow
#### Content Intake Flow
```
Document Upload → Intake Service → OCR → Classification →
Storage (WORM) → Indexing → Workflow Trigger
```
#### Identity Flow
```
User Request → Identity Service → eIDAS/DID Verification →
VC Issuance → Wallet Storage → Access Grant
```
#### Dataroom Flow
```
Deal Creation → Dataroom Service → Document Upload →
Access Control (OPA) → Watermarking → Presigned URLs
```
## Technology Stack
### Frontend
- **Framework**: Next.js 14+
- **UI Library**: React 18+
- **Styling**: Tailwind CSS
- **Components**: shadcn/ui
- **State Management**: Zustand / React Query
### Backend
- **Runtime**: Node.js 18+ (TypeScript)
- **API Framework**: NestJS / Fastify
- **Workflow Engine**: Temporal / AWS Step Functions
- **Message Queue**: Redis / Kafka
### Infrastructure
- **Container Orchestration**: Kubernetes
- **Infrastructure as Code**: Terraform
- **CI/CD**: GitHub Actions
- **Monitoring**: OpenTelemetry + Grafana
- **Logging**: Structured logging (JSON)
### Data Stores
- **Primary Database**: PostgreSQL
- **Cache**: Redis
- **Search**: OpenSearch
- **Object Storage**: S3 / GCS (WORM mode)
- **Key Management**: KMS / HSM
### Security
- **Secrets Management**: SOPS + age / External Secrets
- **Identity**: OIDC + DID (did:key, did:web)
- **Signing**: eIDAS qualified signatures
- **Policy Engine**: OPA (Open Policy Agent)
- **SBOM**: Syft
- **Vulnerability Scanning**: Grype
- **Image Signing**: Cosign
## Design Principles
1. **Security First**: All systems designed with security in mind
2. **Immutable Infrastructure**: Infrastructure as code, version controlled
3. **Observability**: Comprehensive logging, metrics, and tracing
4. **Scalability**: Horizontal scaling, stateless services
5. **Resilience**: Graceful degradation, circuit breakers
6. **Compliance**: eIDAS, data retention, audit trails
## Threat Models
Threat models for each service are located in `threat-models/`. They use STRIDE methodology:
- **S**poofing
- **T**ampering
- **R**epudiation
- **I**nformation Disclosure
- **D**enial of Service
- **E**levation of Privilege
## Data Models
### Core Entities
- **User**: Member of The Order
- **Document**: Legal document, treaty, etc.
- **Deal**: Business transaction with dataroom
- **Matter**: Legal matter with associated documents
- **Identity**: Digital identity (eIDAS/DID)
- **Credential**: Verifiable credential
### Relationships
See entity relationship diagrams in `data-models/`.
## API Design
### REST APIs
- Follow RESTful principles
- Use OpenAPI/Swagger for documentation
- Version APIs: `/v1/`, `/v2/`, etc.
- Use proper HTTP status codes
- Include request/response examples
### GraphQL (if applicable)
- Use GraphQL for complex queries
- Implement proper authorization
- Use DataLoader for N+1 queries
## Deployment Architecture
### Environments
- **Development**: Local development
- **Staging**: Pre-production testing
- **Production**: Live environment
### Deployment Strategy
- **Blue-Green Deployment**: For zero-downtime updates
- **Canary Releases**: For gradual rollouts
- **Feature Flags**: For controlled feature releases
### Infrastructure Regions
- Primary region: EU (for eIDAS compliance)
- Secondary region: Backup/DR
- CDN: Global distribution for static assets
## Monitoring & Observability
### Metrics
- Application metrics (Prometheus)
- Infrastructure metrics (cloud provider)
- Business metrics (custom dashboards)
### Logging
- Structured logging (JSON)
- Centralized log aggregation
- Log retention policies
### Tracing
- Distributed tracing (OpenTelemetry)
- Request flow visualization
- Performance analysis
## Disaster Recovery
### Backup Strategy
- Database backups: Daily full, hourly incremental
- Object storage: Cross-region replication
- Configuration: Version controlled
### Recovery Procedures
- RTO (Recovery Time Objective): 4 hours
- RPO (Recovery Point Objective): 1 hour
- Runbooks in `docs/governance/runbooks/`
## Future Considerations
- Multi-cloud deployment
- Edge computing for low latency
- Machine learning for document classification
- Blockchain integration for notarization
## References
- [ADR Template](adrs/README.md)
- [Threat Models](threat-models/)
- [Data Models](data-models/)
- [API Documentation](../api/)

View File

@@ -0,0 +1,65 @@
# Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for The Order project.
## What is an ADR?
An Architecture Decision Record is a document that captures an important architectural decision made along with its context and consequences.
## ADR Format
Each ADR should follow this structure:
```markdown
# ADR-XXX: [Title]
## Status
[Proposed | Accepted | Deprecated | Superseded]
## Context
Describe the issue that is motivating this decision or change.
## Decision
State the architectural decision that is being made.
## Consequences
Describe the consequences, both positive and negative, of this decision.
## Alternatives Considered
List alternatives that were considered and why they were rejected.
## References
Links to related ADRs, issues, or documentation.
```
## ADR Numbering
ADRs are numbered sequentially:
- `adr-001-*.md`
- `adr-002-*.md`
- etc.
## Creating a New ADR
1. Create a new file: `adr-XXX-short-title.md`
2. Use the template above
3. Set status to "Proposed"
4. Create a PR for discussion
5. Update status to "Accepted" after approval
## ADR Lifecycle
1. **Proposed**: Initial proposal, under discussion
2. **Accepted**: Decision has been made and approved
3. **Deprecated**: Decision is no longer followed
4. **Superseded**: Replaced by a newer ADR
## Current ADRs
*No ADRs yet. Create the first one using the template above.*
## References
- [ADR Template](https://github.com/joelparkerhenderson/architecture-decision-record)
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)

View File

@@ -0,0 +1,235 @@
# Contributing to The Order
Thank you for your interest in contributing to The Order! This document provides guidelines and instructions for contributing.
## Code of Conduct
By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
## Getting Started
1. Fork the repository
2. Clone your fork: `git clone https://github.com/your-username/the-order.git`
3. Create a branch: `git checkout -b feature/your-feature-name`
4. Install dependencies: `pnpm install`
5. Make your changes
6. Test your changes: `pnpm test && pnpm lint`
7. Commit your changes (see [Commit Guidelines](#commit-guidelines))
8. Push to your fork: `git push origin feature/your-feature-name`
9. Open a Pull Request
## Development Setup
### Prerequisites
- Node.js >= 18.0.0
- pnpm >= 8.0.0
- Docker (for local services)
- Git
### Local Development
```bash
# Install dependencies
pnpm install
# Start development servers
pnpm dev
# Run tests
pnpm test
# Run linting
pnpm lint
# Type check
pnpm type-check
```
### Environment Setup
1. Copy `.env.example` to `.env.local` in the workspace you're working on
2. Configure required environment variables
3. For secrets, use SOPS (see [Security Policy](SECURITY.md))
## Commit Guidelines
We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Test additions or changes
- `chore`: Build process or auxiliary tool changes
- `perf`: Performance improvements
- `ci`: CI/CD changes
- `revert`: Revert a previous commit
### Examples
```
feat(auth): add OIDC provider support
Implement OAuth2/OIDC flow with support for multiple providers.
Adds configuration for eIDAS integration.
Closes #123
```
```
fix(intake): resolve OCR parsing issue with PDFs
Fixes character encoding problems when processing multi-page PDFs.
Adds proper error handling for corrupted documents.
Fixes #456
```
## Pull Request Process
1. **Update Documentation**: Update relevant documentation for your changes
2. **Add Tests**: Include tests for new features or bug fixes
3. **Update Changelog**: Add entry to CHANGELOG.md (if applicable)
4. **Ensure Tests Pass**: All CI checks must pass
5. **Request Review**: Request review from relevant code owners (see CODEOWNERS)
### PR Title Format
Use the same format as commit messages:
```
feat(scope): brief description
```
### PR Description Template
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
How was this tested?
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] No new warnings
```
## Code Style
### TypeScript
- Use strict TypeScript configuration
- Prefer type over interface for unions/intersections
- Use explicit return types for public functions
- Avoid `any` type
### Formatting
- Use Prettier for code formatting
- Run `pnpm format` before committing
- ESLint rules must pass
### Naming Conventions
- Variables: `camelCase`
- Functions: `camelCase`
- Classes: `PascalCase`
- Constants: `UPPER_SNAKE_CASE`
- Files: `kebab-case` for utilities, `PascalCase` for components
## Testing
### Unit Tests
- Write unit tests for all new features
- Aim for >80% code coverage
- Use descriptive test names
- Follow AAA pattern (Arrange, Act, Assert)
### Integration Tests
- Write integration tests for API endpoints
- Test error cases and edge cases
- Use test fixtures from `packages/test-utils`
### E2E Tests
- E2E tests for critical user flows
- Use Playwright or similar framework
- Run in CI/CD pipeline
## Documentation
### Code Documentation
- Document all public APIs
- Use JSDoc for functions and classes
- Include examples for complex usage
### Architecture Documentation
- Update ADRs for significant architectural decisions
- Document new services in `docs/architecture/`
- Update data flow diagrams if applicable
## Code Review
### For Authors
- Keep PRs focused and small
- Respond to feedback promptly
- Be open to suggestions
- Update PR based on feedback
### For Reviewers
- Be constructive and respectful
- Focus on code, not the person
- Suggest improvements, don't just point out issues
- Approve when satisfied
## Release Process
1. Create release branch from `main`
2. Update version numbers
3. Update CHANGELOG.md
4. Create release PR
5. After approval, tag release
6. CI/CD automatically deploys
## Questions?
- Open an issue for questions
- Check existing documentation
- Ask in discussions
## Additional Resources
- [Architecture Documentation](docs/architecture/README.md)
- [Security Policy](SECURITY.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)

105
docs/governance/SECURITY.md Normal file
View File

@@ -0,0 +1,105 @@
# Security Policy
## Supported Versions
We currently support the following versions with security updates:
| Version | Supported |
| ------- | ------------------ |
| 1.0.x | :white_check_mark: |
| < 1.0 | :x: |
## Reporting a Vulnerability
We take security vulnerabilities seriously. If you discover a security vulnerability, please follow these steps:
1. **Do NOT** open a public GitHub issue
2. Email security details to: security@the-order.org (or your security contact)
3. Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)
### Response Timeline
- **Initial Response**: Within 48 hours
- **Status Update**: Within 7 days
- **Fix Timeline**: Depends on severity (see below)
### Severity Levels
- **Critical**: Remote code execution, authentication bypass, data breach
- Fix timeline: 24-48 hours
- **High**: Privilege escalation, sensitive data exposure
- Fix timeline: 7 days
- **Medium**: Information disclosure, denial of service
- Fix timeline: 30 days
- **Low**: Best practices, defense in depth
- Fix timeline: Next release cycle
## Security Practices
### Secrets Management
- All secrets must be encrypted using SOPS
- Never commit plaintext secrets
- Use environment variables for configuration
- Rotate secrets regularly
- Use short-lived tokens via OIDC
### Code Security
- All code must pass security linting (ESLint security plugins)
- Dependencies are scanned for vulnerabilities (Grype)
- Container images are signed (Cosign)
- SBOM generation for all artifacts (Syft)
### Infrastructure Security
- Immutable infrastructure via Terraform
- Secrets stored in KMS/HSM
- Network policies enforced via Kubernetes
- API gateway with WAF rules
- Regular security audits and penetration testing
### Access Control
- Least privilege principle
- Quarterly access reviews
- MFA required for all production access
- Audit logs for all sensitive operations
### Compliance
- eIDAS compliance for identity services
- Data retention policies per jurisdiction
- WORM storage for legal documents
- Audit trails for all financial transactions
## Security Updates
Security updates are released as:
- **Hotfixes**: For critical vulnerabilities
- **Patch releases**: For high/medium severity issues
- **Regular releases**: For low severity and general improvements
## Disclosure Policy
- Vulnerabilities are disclosed after a fix is available
- Coordinated disclosure with responsible parties
- CVE assignment for eligible vulnerabilities
- Security advisories published in `docs/governance/security-advisories/`
## Contact
- **Security Email**: security@the-order.org
- **PGP Key**: [Link to public key]
- **Security Team**: @the-order/security-team
## Additional Resources
- [Threat Models](docs/architecture/threat-models/)
- [Incident Response Runbook](docs/governance/runbooks/incident-response.md)
- [Security Checklist](docs/governance/security-checklist.md)

15
docs/legal/README.md Normal file
View File

@@ -0,0 +1,15 @@
# Legal Documentation
Generated legal/treaty artifacts, policies, and legal documentation.
## Contents
- **Treaties** - Treaty documents and artifacts
- **Policies** - Legal policies and procedures
- **Compliance** - Compliance documentation
- **Attestations** - Legal attestations and certifications
## Note
This directory contains legal documents and should be treated with appropriate security and access controls.

27
docs/product/README.md Normal file
View File

@@ -0,0 +1,27 @@
# Product Documentation
Product documentation, roadmaps, and PRDs for The Order.
## Contents
- **Roadmaps** - Product roadmaps and feature planning
- **PRDs** - Product Requirements Documents
- **User Guides** - End-user documentation
- **API Documentation** - API reference and guides
## Roadmaps
See `roadmaps/` directory for product roadmaps.
## PRDs
See `prds/` directory for Product Requirements Documents.
## User Guides
See `user-guides/` directory for end-user documentation.
## API Documentation
See `api/` directory for API documentation and reference.