Overview#

Welcome to the GritivaCore codebase tour for new developers! This document provides an overview of the codebase structure, key components, common workflows, setup instructions, and the dependencies and tools required for local development.

Codebase Structure#

The GritivaCore codebase is organized into several top-level directories, each serving a specific purpose:

• app/: Contains the FastAPI control-plane (Python 3.12).
• agentNew/: The agent that runs on each VM, bundled with PyInstaller.
• server-panel/: The React + Vite admin UI.
• gmesh/: The WireGuard mesh daemon, implemented in Go.
• gritiva-docs-backend/ and gritiva-docs-frontend/: The documentation system you are currently reading.
• docs/: Contains markdown documentation within the repository.

Key Components#

Hot Files to Know#

• agentNew/main.py: The event loop for the agent.
• app/main.py: The main FastAPI application.
• agentNew/handlers/scope.py: Manages the scope lifecycle.
• agentNew/handlers/mesh.py: Handles mesh operations.

The Big Mental Model#

The control plane sets the desired state, while the agents reconcile to achieve that state. Most components in the codebase fit into one of these two roles.

Test Layout#

The tests/ directory mirrors the app/ structure, containing per-component pytest suites and integration tests located in tests/e2e/.

Build Commands#

To build and test the application, use the following commands:

• make backend-test
• make agent-build
• make frontend-dev

Dependency Graph#

• The agentNew directory does not depend on anything in app/.
• The app/ directory depends on common/.
• The frontend communicates with the app/ via REST APIs.

Documentation Locations#

For detailed documentation on each subsystem, refer to:

• Scope Concepts
• Mesh Concepts

Setup Instructions#

Follow the setup instructions to configure your local development environment effectively.

Dependencies and Tools#

Ensure you have the necessary dependencies and tools installed to work with the GritivaCore codebase.