NxMesh-old/AGENTS.md

NxMesh - Agent Instructions

This document provides context for AI agents working on the NxMesh project.

Project Overview

NxMesh is a distributed nginx management system using a master-agent architecture:

• Master (Control Plane): Central API, embedded Web UI, configuration distribution, cluster management
• Agent (Data Plane): Sidecar that manages local nginx instances
• Web UI: Vite React-based admin console, embedded and served by master

Quick Links to Documentation

Document	Purpose
README.md	Project overview and quick start
docs/architecture.md	System design and data flow
docs/features.md	Detailed feature specifications
docs/roadmap.md	Development phases and milestones
docs/api.md	REST and gRPC API specifications

| docs/project-structure.md | Code organization |

Technology Stack

Component	Technology
Backend	Rust (Axum, Tonic, SeaORM)
Frontend	React + TypeScript + Vite
Database	PostgreSQL 16+
Cache	Redis
Message Format	Protocol Buffers (gRPC)
Container	Docker
Orchestration	Kubernetes (optional)

Development Environment

This project uses Dev Containers for consistent development:

# All dependencies are pre-installed in the devcontainer
just setup    # Initial setup
just dev      # Start development

Pre-configured Services

The devcontainer includes:

• PostgreSQL database
• Redis cache
• Nginx instance
• Rust toolchain
• Node.js/Bun for frontend

Key Design Decisions

1. Master-Agent Protocol: Bidirectional gRPC streaming for real-time communication
2. Configuration Management: Template-based (Handlebars) with versioning
3. Security: TLS + Shared Secret for agent connections, JWT for API auth
4. Deployment: Support for Docker sidecar, K8s sidecar, and standalone modes

Common Tasks

Adding a New API Endpoint

1. Define route in crates/nxmesh-master/src/api/v1/
2. Add request/response types to shared models
3. Implement handler with proper error handling
4. Add tests
5. Update OpenAPI documentation

Adding a Database Entity

1. Create migration with sea-orm-cli migrate generate <name>
2. Define entity in crates/nxmesh-master/src/db/entities/
3. Add repository in crates/nxmesh-master/src/db/repositories/
4. Update service layer

Adding Agent Functionality

1. Add module in crates/nxmesh-agent/src/
2. Update gRPC protocol if needed (crates/nxmesh-proto/proto/)
3. Implement handler in agent
4. Add corresponding master service

Testing

just test              # All tests
just test-unit         # Unit tests only
just test-integration  # Integration tests

Code Style

• Follow Rust API Guidelines
• Use cargo fmt and cargo clippy
• All public APIs must have doc comments
• Error types should be descriptive and actionable

Questions?

Refer to the documentation in docs/ directory or ask the team.