Add project structure and roadmap documentation
- Created `project-structure.md` to outline the directory layout, crate dependencies, design principles, module guidelines, and naming conventions for the NxMesh codebase. - Introduced `roadmap.md` detailing the development phases, milestones, tasks, deliverables, and resource requirements for the NxMesh project, spanning from foundational setup to enterprise features.
This commit is contained in:
GW_MC
428
docs/project-structure.md
Normal file
428
docs/project-structure.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# NxMesh Project Structure
|
||||
|
||||
This document outlines the recommended project structure for the NxMesh codebase.
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
nxmesh/
|
||||
├── Cargo.toml # Workspace root
|
||||
├── Cargo.lock
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
├── justfile # Task runner
|
||||
├── AGENTS.md # AI agent context
|
||||
├──
|
||||
├── crates/ # Rust workspace crates
|
||||
│ ├── nxmesh-core/ # Shared core library
|
||||
│ │ ├── Cargo.toml
|
||||
│ │ └── src/
|
||||
│ │ ├── lib.rs
|
||||
│ │ ├── models/ # Shared data models
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── organization.rs
|
||||
│ │ │ ├── workspace.rs
|
||||
│ │ │ ├── agent.rs
|
||||
│ │ │ ├── config.rs
|
||||
│ │ │ └── certificate.rs
|
||||
│ │ ├── crypto/ # Encryption, hashing
|
||||
│ │ ├── validation/ # Input validation
|
||||
│ │ └── error.rs # Common error types
|
||||
│ │
|
||||
│ ├── nxmesh-proto/ # Protocol buffers
|
||||
│ │ ├── Cargo.toml
|
||||
│ │ ├── build.rs
|
||||
│ │ └── proto/
|
||||
│ │ ├── agent.proto
|
||||
│ │ ├── config.proto
|
||||
│ │ └── common.proto
|
||||
│ │
|
||||
│ ├── nxmesh-master/ # Control plane
|
||||
│ │ ├── Cargo.toml
|
||||
│ │ └── src/
|
||||
│ │ ├── main.rs
|
||||
│ │ ├── lib.rs
|
||||
│ │ ├── api/ # REST API handlers
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── routes.rs
|
||||
│ │ │ ├── middleware/
|
||||
│ │ │ ├── v1/ # API version 1
|
||||
│ │ │ │ ├── mod.rs
|
||||
│ │ │ │ ├── organizations.rs
|
||||
│ │ │ │ ├── workspaces.rs
|
||||
│ │ │ │ ├── agents.rs
|
||||
│ │ │ │ ├── virtual_hosts.rs
|
||||
│ │ │ │ ├── upstreams.rs
|
||||
│ │ │ │ ├── certificates.rs
|
||||
│ │ │ │ └── metrics.rs
|
||||
│ │ │ └── websocket.rs
|
||||
│ │ ├── grpc/ # gRPC service
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── server.rs
|
||||
│ │ │ ├── agent_service.rs
|
||||
│ │ │ └── interceptor.rs
|
||||
│ │ ├── config/ # Configuration
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ └── settings.rs
|
||||
│ │ ├── db/ # Database layer
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── connection.rs
|
||||
│ │ │ ├── migration.rs
|
||||
│ │ │ └── repositories/
|
||||
│ │ ├── services/ # Business logic
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── organization_service.rs
|
||||
│ │ │ ├── workspace_service.rs
|
||||
│ │ │ ├── agent_service.rs
|
||||
│ │ │ ├── config_service.rs
|
||||
│ │ │ ├── certificate_service.rs
|
||||
│ │ │ └── auth_service.rs
|
||||
│ │ ├── domain/ # Domain entities
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── organization.rs
|
||||
│ │ │ ├── agent.rs
|
||||
│ │ │ └── config.rs
|
||||
│ │ ├── infrastructure/ # External integrations
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── acme/ # Let's Encrypt
|
||||
│ │ │ ├── storage/ # Object storage
|
||||
│ │ │ └── notifier/ # Notifications
|
||||
│ │ ├── events/ # Event bus
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── bus.rs
|
||||
│ │ │ └── handlers.rs
|
||||
│ │ └── cli.rs # CLI commands
|
||||
│ │
|
||||
│ ├── nxmesh-agent/ # Data plane
|
||||
│ │ ├── Cargo.toml
|
||||
│ │ └── src/
|
||||
│ │ ├── main.rs
|
||||
│ │ ├── lib.rs
|
||||
│ │ ├── config/ # Agent configuration
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ └── settings.rs
|
||||
│ │ ├── master/ # Master communication
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── client.rs
|
||||
│ │ │ ├── reconnect.rs
|
||||
│ │ │ └── stream.rs
|
||||
│ │ ├── nginx/ # Nginx management
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── controller.rs
|
||||
│ │ │ ├── config_manager.rs # Symlink-based atomic deployment
|
||||
│ │ │ ├── config_renderer.rs
|
||||
│ │ │ ├── validator.rs
|
||||
│ │ │ ├── docker_sidecar.rs # Docker sidecar (PID namespace sharing)
|
||||
│ │ │ ├── systemd.rs # Standalone mode
|
||||
│ │ │ └── parser.rs # Nginx config parser
|
||||
│ │ ├── health/ # Health monitoring
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── monitor.rs
|
||||
│ │ │ ├── nginx.rs
|
||||
│ │ │ └── system.rs
|
||||
│ │ ├── metrics/ # Metrics collection
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ ├── collector.rs
|
||||
│ │ │ └── exporter.rs
|
||||
│ │ ├── cache/ # Local caching
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ └── config_cache.rs
|
||||
│ │ ├── watch/ # File watchers
|
||||
│ │ │ ├── mod.rs
|
||||
│ │ │ └── config_watch.rs
|
||||
│ │ └── cli.rs # CLI commands
|
||||
│ │
|
||||
│ └── nxmesh-cli/ # CLI tool
|
||||
│ ├── Cargo.toml
|
||||
│ └── src/
|
||||
│ ├── main.rs
|
||||
│ ├── commands/ # CLI commands
|
||||
│ │ ├── mod.rs
|
||||
│ │ ├── login.rs
|
||||
│ │ ├── agent.rs
|
||||
│ │ ├── config.rs
|
||||
│ │ └── deploy.rs
|
||||
│ └── api/ # API client
|
||||
│
|
||||
├── frontend/ # Web UI (embedded in master)
|
||||
│ ├── package.json
|
||||
│ ├── vite.config.ts
|
||||
│ ├── tsconfig.json
|
||||
│ ├── index.html
|
||||
│ ├── src/
|
||||
│ │ ├── main.tsx
|
||||
│ │ ├── App.tsx
|
||||
│ │ ├── components/ # Reusable components
|
||||
│ │ │ ├── common/
|
||||
│ │ │ ├── layout/
|
||||
│ │ │ └── forms/
|
||||
│ │ ├── pages/ # Page components
|
||||
│ │ │ ├── Dashboard/
|
||||
│ │ │ ├── Agents/
|
||||
│ │ │ ├── Configurations/
|
||||
│ │ │ ├── Certificates/
|
||||
│ │ │ └── Settings/
|
||||
│ │ ├── hooks/ # React hooks
|
||||
│ │ ├── stores/ # State management (Zustand)
|
||||
│ │ ├── api/ # API client
|
||||
│ │ ├── types/ # TypeScript types
|
||||
│ │ ├── utils/ # Utilities
|
||||
│ │ └── styles/ # CSS/Tailwind
|
||||
│ └── public/
|
||||
│
|
||||
│ # Build output (dist/) is embedded into master binary
|
||||
│ # Master serves static files at root path ("/")
|
||||
│
|
||||
├── migrations/ # Database migrations
|
||||
│ └── sea-orm/
|
||||
│ ├── Cargo.toml
|
||||
│ └── src/
|
||||
│
|
||||
├── tests/ # Integration tests
|
||||
│ ├── integration/
|
||||
│ │ ├── master_api_tests.rs
|
||||
│ │ ├── agent_master_tests.rs
|
||||
│ │ └── config_flow_tests.rs
|
||||
│ └── fixtures/
|
||||
│
|
||||
├── scripts/ # Build/utility scripts
|
||||
│ ├── build.sh
|
||||
│ ├── test.sh
|
||||
│ └── release.sh
|
||||
│
|
||||
├── deploy/ # Deployment configs
|
||||
│ ├── docker/
|
||||
│ │ ├── master.Dockerfile
|
||||
│ │ ├── agent.Dockerfile
|
||||
│ │ └── docker-compose.yml
|
||||
│ ├── k8s/
|
||||
│ │ ├── namespace.yaml
|
||||
│ │ ├── master/
|
||||
│ │ ├── agent/
|
||||
│ │ └── helm/
|
||||
│ └── terraform/
|
||||
│
|
||||
├── docs/ # Documentation
|
||||
│ ├── architecture.md
|
||||
│ ├── features.md
|
||||
│ ├── roadmap.md
|
||||
│ ├── api.md
|
||||
│ ├── deployment.md
|
||||
│ └── project-structure.md
|
||||
│
|
||||
└── .devcontainer/ # Dev container
|
||||
├── devcontainer.json
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
└── nginx/
|
||||
```
|
||||
|
||||
## Crate Dependencies
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Workspace Crates"
|
||||
CLI[nxmesh-cli]
|
||||
AGENT[nxmesh-agent]
|
||||
MASTER[nxmesh-master]
|
||||
PROTO[nxmesh-proto]
|
||||
CORE[nxmesh-core]
|
||||
end
|
||||
|
||||
CORE --> PROTO
|
||||
AGENT --> CORE
|
||||
AGENT --> PROTO
|
||||
MASTER --> CORE
|
||||
MASTER --> PROTO
|
||||
CLI --> CORE
|
||||
```
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
### 1. Separation of Concerns
|
||||
|
||||
- **nxmesh-core**: Only shared types and utilities
|
||||
- **nxmesh-master**: Only control plane logic
|
||||
- **nxmesh-agent**: Only data plane logic
|
||||
- **frontend**: Only UI logic
|
||||
|
||||
### 2. Domain-Driven Design (in Master)
|
||||
|
||||
```
|
||||
domain/ # Domain entities (pure logic)
|
||||
services/ # Application services (orchestration)
|
||||
repositories/ # Data access abstraction
|
||||
api/ # Interface adapters (HTTP, gRPC)
|
||||
infrastructure/ # External concerns
|
||||
```
|
||||
|
||||
### 3. Agent Modularity
|
||||
|
||||
Each major concern in the agent is a separate module:
|
||||
- `nginx/`: All nginx-specific code
|
||||
- `master/`: All master communication code
|
||||
- `health/`: All health monitoring code
|
||||
- `metrics/`: All metrics code
|
||||
|
||||
### 4. Configuration Management
|
||||
|
||||
Use hierarchical config:
|
||||
1. Default values (in code)
|
||||
2. Config file (`/etc/nxmesh/*.toml`)
|
||||
3. Environment variables
|
||||
4. Command-line arguments (highest priority)
|
||||
|
||||
## Module Guidelines
|
||||
|
||||
### API Versioning
|
||||
|
||||
- Always version REST APIs: `/api/v1/...`
|
||||
- Maintain backward compatibility within major versions
|
||||
- Use feature flags for gradual rollouts
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Use `thiserror` for error definitions
|
||||
- Propagate errors with context
|
||||
- Convert to user-friendly messages at API boundary
|
||||
|
||||
### Testing Structure
|
||||
|
||||
```rust
|
||||
// In each module
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_feature() {
|
||||
// unit tests
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Unit tests: In same file as code
|
||||
- Integration tests: In `tests/` directory
|
||||
- E2E tests: Separate crate or external repo
|
||||
|
||||
### Documentation
|
||||
|
||||
- All public APIs must have doc comments
|
||||
- Include examples in doc comments
|
||||
- Keep README files in each crate
|
||||
|
||||
## Build Configuration
|
||||
|
||||
### Workspace Cargo.toml
|
||||
|
||||
```toml
|
||||
[workspace]
|
||||
members = [
|
||||
"crates/nxmesh-core",
|
||||
"crates/nxmesh-proto",
|
||||
"crates/nxmesh-master",
|
||||
"crates/nxmesh-agent",
|
||||
"crates/nxmesh-cli",
|
||||
]
|
||||
resolver = "3"
|
||||
|
||||
[workspace.dependencies]
|
||||
# Core dependencies
|
||||
tokio = { version = "1", features = ["full"] }
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
thiserror = "1"
|
||||
tracing = "0.1"
|
||||
|
||||
# Web framework
|
||||
axum = "0.7"
|
||||
tower = "0.4"
|
||||
tower-http = "0.5"
|
||||
|
||||
# gRPC
|
||||
tonic = "0.11"
|
||||
prost = "0.12"
|
||||
|
||||
# Database
|
||||
sea-orm = "2.0.0-rc"
|
||||
sea-orm-migration = "2.0.0-rc"
|
||||
|
||||
# Async
|
||||
async-trait = "0.1"
|
||||
futures = "0.3"
|
||||
|
||||
# Serialization
|
||||
serde_json = "1"
|
||||
toml = "0.8"
|
||||
|
||||
# HTTP
|
||||
reqwest = { version = "0.12", default-features = false }
|
||||
|
||||
# Crypto
|
||||
sha2 = "0.10"
|
||||
hex = "0.4"
|
||||
|
||||
# Testing
|
||||
tokio-test = "0.4"
|
||||
mockall = "0.12"
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Files
|
||||
- Use `snake_case` for file names
|
||||
- Module entry point: `mod.rs` or `{module_name}.rs`
|
||||
|
||||
### Types
|
||||
- Structs/Enums: `PascalCase`
|
||||
- Traits: `PascalCase` (often ending in `able` or with verb prefix)
|
||||
- Functions/Methods: `snake_case`
|
||||
- Constants: `SCREAMING_SNAKE_CASE`
|
||||
- Generic parameters: Single uppercase letter (`T`, `K`, `V`)
|
||||
|
||||
### Error Types
|
||||
- Suffix with `Error`: `ConfigError`, `AgentError`
|
||||
- Group in `error.rs` or `errors/` module
|
||||
|
||||
### Feature Flags
|
||||
- Use `kebab-case`: `postgres-native`, `tls-rustls`
|
||||
|
||||
## CI/CD Structure
|
||||
|
||||
```yaml
|
||||
# .github/workflows/
|
||||
├── ci.yml # PR checks
|
||||
├── test.yml # Test suite
|
||||
├── release.yml # Release builds
|
||||
├── docker.yml # Docker image builds
|
||||
└── docs.yml # Documentation deploy
|
||||
```
|
||||
|
||||
## Scripts
|
||||
|
||||
Common operations should have just commands:
|
||||
|
||||
```justfile
|
||||
# Development
|
||||
just dev # Start all services
|
||||
just dev-backend # Start backend only
|
||||
just dev-frontend # Start frontend only
|
||||
|
||||
# Testing
|
||||
just test # Run all tests
|
||||
just test-unit # Unit tests only
|
||||
just test-integration # Integration tests
|
||||
|
||||
# Building
|
||||
just build # Build all
|
||||
just build-master # Build master only
|
||||
just build-agent # Build agent only
|
||||
|
||||
# Database
|
||||
just db-migrate # Run migrations
|
||||
just db-reset # Reset database
|
||||
just db-console # Open psql
|
||||
|
||||
# Deployment
|
||||
just docker-build # Build Docker images
|
||||
just k8s-deploy # Deploy to Kubernetes
|
||||
```
|
||||
Reference in New Issue
Block a user