# 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 ("/") │ ├── migration/ # Database migrations │ ├── 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 ```