Setting up the repository

This guide walks you through setting up the DeepIntShield repository for local development, from prerequisites to running your first development server.

Prerequisites

Before setting up the repository, ensure you have the following tools installed:

Go (1.25.5)
Node.js (>= 18.0.0) and npm
Make
Docker (optional, for containerized development)
Air (for hot reloading, auto-installed by Makefile when needed)
golangci-lint (optional, for linting)
goimports (optional, for code formatting)

Clone the Repository

# Clone the repository
git clone https://github.com/maximhq/deepintshield.git
cd deepintshield

# Verify the repository structure
ls -la

You should see the main directories: core/, framework/, transports/, ui/, plugins/, docs/, etc.

Repository Structure

DeepIntShield uses a modular architecture with the following structure:

deepintshield/
├── core/                # Core functionality and shared components
│   ├── providers/       # Provider-specific implementations (OpenAI, Anthropic, etc.)
│   ├── schemas/         # Interfaces and structs used throughout DeepIntShield
│   └── deepintshield.go       # Main DeepIntShield implementation
├── framework/           # Framework components for common functionality
│   ├── configstore/     # Configuration storages
│   ├── logstore/        # Request logging storages
│   └── vectorstore/     # Vector storages
├── transports/          # HTTP gateway and other interface layers
│   └── deepintshield-http/    # HTTP transport implementation
├── ui/                  # Web interface for HTTP gateway
├── plugins/             # First party plugins
├── docs/                # Documentation and guides
└── tests/               # Comprehensive test suites

The system uses a provider-agnostic approach with well-defined interfaces in core/schemas/ for easy extension to new AI providers.

Learn More About the Architecture:

Request Flow - Deep dive into how requests are processed from transport to provider
Plugin System - How plugins extend functionality
Framework Components - Shared storage and utilities
MCP Integration - Model Context Protocol implementation

Development Environment Setup

Quick Start (Recommended)

The fastest way to get started is using the complete development environment:

# Start complete development environment (UI + API with hot reload)
make dev

This command will:

Install UI dependencies automatically
Install Air for hot reloading
Set up the Go workspace with local modules
Start the Next.js development server (port 3000)
Start the API server with UI proxy (port 8080)

Access the application at: http://localhost:8080

Manual Setup (Alternative)

If you prefer to set up components manually:

1. Install UI Dependencies

# Install UI dependencies and tools
make install-ui

2. Install Air for Hot Reloading

# Install Air if not already installed
make install-air

3. Set Up Go Workspace

# Set up Go workspace with all local modules
make setup-workspace

This creates a go.work file that links all local modules for development.

4. Build the Application

# Build UI and binary
make build

# Build with local go.work modules (for development)
make build LOCAL=1

# Build with specific version
make build VERSION=1.0.0

# Cross-compile for different platforms
make build GOOS=linux GOARCH=amd64

# Build with dynamic linking (Linux only)
make build DYNAMIC=1

5. Run the Application

# Run without hot reload
make run

# Or with hot reload (development)
make dev

Available Make Commands

The Makefile provides numerous commands for development:

Development Commands

make dev          # Start complete development environment (recommended)
make build        # Build UI and deepintshield-http binary
make run          # Build and run (no hot reload)
make clean        # Clean build artifacts

Testing Commands

make test         # Run deepintshield-http tests
make test-core    # Run all core tests
make test-core PROVIDER=openai  # Run specific provider tests
make test-core PROVIDER=openai TESTCASE=SpeechSynthesisStreamAdvanced/MultipleVoices_Streaming/StreamingVoice_echo  # Run specific test case
make test-plugins # Run plugin tests
make test-governance  # Run governance tests
make test-governance TESTCASE=TestVKBudgetExceeded  # Run specific governance test
make test-governance PATTERN=Budget  # Run governance tests matching pattern
make test-all     # Run all tests
make clean-test-reports  # Clean test reports
make generate-html-reports  # Convert XML to HTML reports

Workspace Management

make setup-workspace  # Set up Go workspace for local development
make work-clean       # Remove local go.work files

UI Commands

make install-ui   # Install UI dependencies
make build-ui     # Build UI for production

Docker Commands

make build-docker-image  # Build Docker image
make docker-run         # Run Docker container

Documentation

make docs         # Start local documentation server

Code Quality

make lint         # Run linter for Go code
make fmt          # Format Go code

Tool Installation

make install-gotestsum     # Install gotestsum for test reporting
make install-junit-viewer  # Install junit-viewer for HTML reports

Environment Variables

You can customize the development environment with these variables:

# Server configuration
HOST=localhost                    # Server host (default: localhost)
PORT=8080                        # Server port (default: 8080)

# Logging
LOG_STYLE=json                   # Logger format: json|pretty (default: json)
LOG_LEVEL=info                   # Logger level: debug|info|warn|error (default: info)

# Prometheus
PROMETHEUS_LABELS="env=dev"      # Labels for Prometheus metrics

# App directory
APP_DIR=                         # App data directory (empty by default, /app/data recommended for containers)

# Build configuration
VERSION=dev-build                # Build version (default: dev-build)
LOCAL=                           # Use local go.work for builds (e.g., make build LOCAL=1)

Example with custom settings:

PORT=3001 LOG_STYLE=pretty LOG_LEVEL=debug APP_DIR=/app/data make dev

Understanding DeepIntShield Architecture

Before diving into development, it’s helpful to understand how DeepIntShield works internally. The architecture documentation provides detailed insights into:

Core Components

Request Flow - How requests flow through the system from transport to provider and back
Concurrency - Worker pools and threading model
MCP Integration - Model Context Protocol implementation
Plugin System - How plugins extend core functionality

Framework Layer

What is Framework - Shared storage and utilities overview
Config Store - Configuration persistence patterns
Log Store - Request logging and analytics
Vector Store - Semantic search and caching

Plugins & Transports

Plugin Architecture - Plugin development patterns and execution model
Transport Layer - HTTP and other transport implementations

Development Workflow

1. Start Development Environment

make dev

2. Make Your Changes

Core changes: Edit files in core/
API changes: Edit files in transports/deepintshield-http/
UI changes: Edit files in ui/
Plugin changes: Edit files in plugins/

3. Test Your Changes

# Run all tests
make test-all

# Run specific provider tests
make test-core PROVIDER=openai

# Run specific test case (TESTCASE must be a slash-delimited nested path matching the test hierarchy)
make test-core PROVIDER=elevenlabs TESTCASE=SpeechSynthesisStreamAdvanced/MultipleVoices_Streaming/StreamingVoice_echo

# Run HTTP transport tests
make test

# Run plugin tests
make test-plugins

# View test reports (after running tests)
open test-reports/index.html

4. Verify Code Quality

# Format code
make fmt

# Run linter
make lint

5. Build for Production

# Build everything
make build

# Or build Docker image
make build-docker-image

Troubleshooting

Common Issues

Go workspace issues:

# Reset the workspace
make work-clean
make setup-workspace

UI dependency issues:

# Clean and reinstall UI dependencies
rm -rf ui/node_modules ui/.next
make install-ui

Port conflicts:

# Use different ports
PORT=9090 make dev

If an process is running on a port you need to use, you may need to terminate or kill it first:

# Kill the process on port 8080
kill -9 $(lsof -t -i:8080)

Hot reload not working:

# Ensure Air is installed
which air || go install github.com/air-verse/air@latest

# Check if .air.toml exists in transports/deepintshield-http/
ls transports/deepintshield-http/.air.toml

Getting Help

Check logs: Development logs appear in your terminal
Verify prerequisites: Ensure Go, Node.js, and make are properly installed
Clean build: Run make clean and try again
Discord: Join our Discord community for real-time help

Next Steps

Once your development environment is running:

Explore the UI: Visit http://localhost:8080 to see the web interface
Make API calls: Test the API endpoints at http://localhost:8080/v1/
Understand the architecture: Read our request flow documentation to understand how DeepIntShield works internally
Read the documentation: Check out our complete documentation
Review contribution guidelines: See our code conventions and PR guidelines

Quick Reference

# Essential commands for daily development
make dev          # Start development environment
make test-all     # Run all tests
make fmt          # Format code
make clean        # Clean build artifacts
make help         # Show all available commands

Happy coding! 🚀