GW_MC/NxMesh-old
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2e9ad4fc210c12ab52bd72253fbc7faa8742ff03
NxMesh-old/docs/project-structure.md
GW_MC 43b2e44d95 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.
2026-03-03 04:13:31 +00:00

429 lines
13 KiB
Markdown
Raw Blame History

# 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 View Git Blame Copy Permalink