docs: align internal docs to enterprise standards
All checks were successful
CI / verify (push) Successful in 2m33s
All checks were successful
CI / verify (push) Successful in 2m33s
Add canonical operations/security/access/feature docs and fix path integrity to improve onboarding and incident readiness.
This commit is contained in:
Joseph Doherty
164
README.md
164
README.md
@@ -5,7 +5,6 @@
|
||||
**Peer-to-Peer Data Synchronization Middleware for .NET**
|
||||
|
||||
[](https://dotnet.microsoft.com/)
|
||||
[](LICENSE)
|
||||
|
||||
## Status
|
||||
|
||||
@@ -22,9 +21,18 @@ CBDDC is not a database - it's a **sync layer** that plugs into your existing da
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Ownership and Support](#ownership-and-support)
|
||||
- [Architecture](#architecture)
|
||||
- [Key Features](#key-features)
|
||||
- [Installation](#installation)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Configuration and Secrets](#configuration-and-secrets)
|
||||
- [Build, Test, and Quality Gates](#build-test-and-quality-gates)
|
||||
- [Deployment and Rollback](#deployment-and-rollback)
|
||||
- [Operations and Incident Response](#operations-and-incident-response)
|
||||
- [Security and Compliance Posture](#security-and-compliance-posture)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Change Governance](#change-governance)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Integrating with Your Database](#integrating-with-your-database)
|
||||
- [Cloud Deployment](#cloud-deployment)
|
||||
@@ -32,7 +40,6 @@ CBDDC is not a database - it's a **sync layer** that plugs into your existing da
|
||||
- [Use Cases](#use-cases)
|
||||
- [Documentation](#documentation)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
@@ -50,6 +57,15 @@ Your application continues to read and write to its database as usual. CBDDC wor
|
||||
|
||||
---
|
||||
|
||||
## Ownership and Support
|
||||
|
||||
- **Owning team**: CBDDC Core Maintainers
|
||||
- **Issue reporting**: [GitHub Issues](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/issues)
|
||||
- **Usage/support questions**: [GitHub Discussions](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/discussions)
|
||||
- **Incident escalation for active deployments**: Follow your local on-call process first, then attach CBDDC diagnostics from `docs/runbook.md`
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
@@ -163,6 +179,107 @@ dotnet add package CBDDC.Network
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before onboarding a new node, verify:
|
||||
|
||||
- .NET SDK/runtime required by selected packages (recommended: .NET 8+)
|
||||
- Network access for configured TCP/UDP sync ports
|
||||
- Persistent storage path with write permissions for database and backups
|
||||
- Access to deployment secrets (cluster `AuthToken`, connection strings, environment-specific config)
|
||||
- Ability to run health checks (`/health` in hosted mode)
|
||||
|
||||
---
|
||||
|
||||
## Configuration and Secrets
|
||||
|
||||
CBDDC runtime behavior should be configured from environment-specific settings, not hardcoded values.
|
||||
|
||||
- Required runtime settings:
|
||||
- `NodeId`
|
||||
- `TcpPort` (and `UdpPort` when discovery is enabled)
|
||||
- `AuthToken` (secret; do not commit)
|
||||
- Persistence connection/database path
|
||||
- Secret handling guidance:
|
||||
- Keep secrets in a secret manager or protected environment variables
|
||||
- Rotate tokens during maintenance windows and validate mesh convergence after rotation
|
||||
- Avoid exposing tokens in logs, screenshots, or troubleshooting output
|
||||
|
||||
See `docs/security.md` and `docs/production-hardening.md` for detailed control guidance.
|
||||
|
||||
---
|
||||
|
||||
## Build, Test, and Quality Gates
|
||||
|
||||
Run these checks before merge or release:
|
||||
|
||||
```bash
|
||||
dotnet restore
|
||||
dotnet build
|
||||
dotnet test
|
||||
```
|
||||
|
||||
Recommended release gates:
|
||||
|
||||
- Unit/integration tests pass
|
||||
- Health endpoint reports healthy in staging after deployment
|
||||
- No unresolved high-severity issues in deployment or runbook checklists
|
||||
|
||||
---
|
||||
|
||||
## Deployment and Rollback
|
||||
|
||||
Canonical deployment procedures are documented in:
|
||||
|
||||
- `docs/deployment.md` (promotion flow, validation gates, rollback path)
|
||||
- `docs/deployment-lan.md` (LAN deployment details)
|
||||
- `docs/deployment-modes.md` (hosted mode behavior)
|
||||
- `docs/production-hardening.md` (operational hardening controls)
|
||||
|
||||
---
|
||||
|
||||
## Operations and Incident Response
|
||||
|
||||
Use `docs/runbook.md` as the primary operational runbook. It includes:
|
||||
|
||||
- Alert triage sequence
|
||||
- Escalation path and severity mapping
|
||||
- Recovery and verification steps
|
||||
- Post-incident follow-up expectations
|
||||
|
||||
For peer lifecycle incidents, use `docs/peer-deprecation-removal-runbook.md`.
|
||||
|
||||
---
|
||||
|
||||
## Security and Compliance Posture
|
||||
|
||||
- Primary protections: authenticated peer communication and encrypted transport options in CBDDC networking components
|
||||
- Sensitive data handling: classify data by environment and apply least privilege on runtime access
|
||||
- Operational controls: hardening, key rotation, and monitoring requirements are documented in `docs/security.md` and `docs/access.md`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issue patterns and step-by-step remediation are documented in `docs/troubleshooting.md`.
|
||||
|
||||
High-priority troubleshooting topics:
|
||||
|
||||
- Peer unreachable or lagging confirmation state
|
||||
- Persistence faults and backup restore flow
|
||||
- Authentication mismatch or configuration drift
|
||||
|
||||
---
|
||||
|
||||
## Change Governance
|
||||
|
||||
- Use short-lived branches and pull requests for every change
|
||||
- Require review before merge to protected branches
|
||||
- Run build/test/health validation before release
|
||||
- Record release-impacting changes in `CHANGELOG.md` and link related deployment notes
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Define Your Database Context
|
||||
@@ -608,13 +725,14 @@ Console.WriteLine($"Peers: {status.ConnectedPeers}");
|
||||
|
||||
- **[Architecture & Concepts](docs/architecture.md)** - HLC, Gossip, Vector Clocks, Hash Chains
|
||||
- **[Conflict Resolution](docs/conflict-resolution.md)** - LWW vs Recursive Merge
|
||||
- **[Oplog & CDC](docs/oplog-cdc.md)** - How change tracking works
|
||||
- **[Oplog & CDC Design](docs/database-sync-manager-design.md)** - How change tracking works
|
||||
|
||||
### Deployment
|
||||
|
||||
- **[Production Guide](docs/production-hardening.md)** - Configuration, monitoring, best practices
|
||||
- **[Cloud Deployment](docs/cloud-deployment.md)** - ASP.NET Core hosting
|
||||
- **[Deployment Runbook](docs/deployment.md)** - Promotion flow, validation, rollback
|
||||
- **[Deployment Modes](docs/deployment-modes.md)** - Single-cluster deployment strategy
|
||||
- **[Operations Runbook](docs/runbook.md)** - Incident triage and recovery
|
||||
|
||||
### API
|
||||
|
||||
@@ -711,41 +829,3 @@ dotnet run
|
||||
### Code of Conduct
|
||||
|
||||
Be respectful, inclusive, and constructive. We're all here to learn and build great software together.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
CBDDC is licensed under the **MIT License**.
|
||||
|
||||
```
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 MrDevRobot
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software...
|
||||
```
|
||||
|
||||
See [LICENSE](LICENSE) file for full details.
|
||||
|
||||
---
|
||||
|
||||
## Give it a Star!
|
||||
|
||||
If you find CBDDC useful, please **give it a star** on GitHub! It helps others discover the project and motivates us to keep improving it.
|
||||
|
||||
<div align="center">
|
||||
|
||||
### [Star on GitHub](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net)
|
||||
|
||||
**Thank you for your support!**
|
||||
|
||||
**Built with care for the .NET community**
|
||||
|
||||
[Report Bug](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/issues) | [Request Feature](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/issues) | [Discussions](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net/discussions)
|
||||
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user