Redflag/docs/4_LOG/October_2025/Development-Documentation/DEVELOPMENT.md

RedFlag Development Guide

Prerequisites

• Go 1.21+ - Backend and agent development
• Node.js 18+ - Web dashboard development
• Docker & Docker Compose - Database and containerized deployments
• Make - Build automation (optional but recommended)

---

Quick Start (Development)

# Clone repository
git clone https://github.com/Fimeg/RedFlag.git
cd RedFlag

# Start database
docker-compose up -d postgres

# Build and run server
cd aggregator-server
go mod tidy
go build -o redflag-server cmd/server/main.go
./redflag-server --setup
./redflag-server

# Build and run agent (separate terminal)
cd aggregator-agent
go mod tidy
go build -o redflag-agent cmd/agent/main.go
./redflag-agent --server http://localhost:8080 --token <your-token> --register

# Run web dashboard (separate terminal)
cd aggregator-web
npm install
npm run dev

---

Makefile Commands

make help           # Show all available commands
make build-all      # Build server, agent, and web
make build-server   # Build server binary
make build-agent    # Build agent binary
make build-web      # Build web dashboard

make db-up          # Start PostgreSQL container
make db-down        # Stop PostgreSQL container
make db-reset       # Reset database (WARNING: destroys data)

make server         # Run server with auto-reload
make agent          # Run agent
make web            # Run web dev server

make test           # Run all tests
make test-server    # Run server tests
make test-agent     # Run agent tests

make clean          # Clean build artifacts
make docker-build   # Build Docker images
make docker-up      # Start all services in Docker
make docker-down    # Stop all Docker services

---

Project Structure

RedFlag/
├── aggregator-server/          # Go server backend
│   ├── cmd/server/            # Main server entry point
│   ├── internal/
│   │   ├── api/               # REST API handlers and middleware
│   │   ├── database/          # Database layer with migrations
│   │   ├── models/            # Data models and structs
│   │   └── config/            # Configuration management
│   ├── Dockerfile
│   └── go.mod

├── aggregator-agent/           # Cross-platform Go agent
│   ├── cmd/agent/             # Agent main entry point
│   ├── internal/
│   │   ├── client/           # HTTP client with token renewal
│   │   ├── config/           # Configuration system
│   │   ├── scanner/          # Update scanners (APT, DNF, Winget, etc.)
│   │   ├── installer/        # Package installers
│   │   ├── system/           # System information collection
│   │   └── service/          # Windows service integration
│   ├── install.sh             # Linux installation script
│   └── go.mod

├── aggregator-web/             # React dashboard
│   ├── src/
│   │   ├── components/       # Reusable UI components
│   │   ├── pages/            # Page components
│   │   ├── hooks/            # Custom React hooks
│   │   ├── lib/              # API client and utilities
│   │   └── types/            # TypeScript type definitions
│   ├── Dockerfile
│   └── package.json

├── docs/                       # Documentation
├── docker-compose.yml          # Development environment
├── Makefile                    # Build automation
└── README.md

---

Building from Source

Server

cd aggregator-server
go mod tidy
go build -o redflag-server cmd/server/main.go

Agent

cd aggregator-agent
go mod tidy

# Linux
go build -o redflag-agent cmd/agent/main.go

# Windows (cross-compile from Linux)
GOOS=windows GOARCH=amd64 go build -o redflag-agent.exe cmd/agent/main.go

# macOS (future support)
GOOS=darwin GOARCH=amd64 go build -o redflag-agent cmd/agent/main.go

Web Dashboard

cd aggregator-web
npm install
npm run build  # Production build
npm run dev    # Development server

---

Running Tests

Server Tests

cd aggregator-server
go test ./...
go test -v ./internal/api/...    # Verbose output for specific package
go test -cover ./...              # With coverage

Agent Tests

cd aggregator-agent
go test ./...
go test -v ./internal/scanner/... # Specific package

Web Tests

cd aggregator-web
npm test
npm run test:coverage

---

Database Migrations

Migrations are in aggregator-server/internal/database/migrations/

Create New Migration

# Naming: XXX_description.up.sql
touch aggregator-server/internal/database/migrations/013_add_feature.up.sql

Run Migrations

cd aggregator-server
./redflag-server --migrate

Migration Best Practices

• Always use .up.sql suffix
• Include rollback logic in comments
• Test migrations on copy of production data
• Keep migrations idempotent when possible

---

Docker Development

Build All Images

docker-compose build

Build Specific Service

docker-compose build aggregator-server
docker-compose build aggregator-agent
docker-compose build aggregator-web

View Logs

docker-compose logs -f                    # All services
docker-compose logs -f aggregator-server  # Specific service

Rebuild Without Cache

docker-compose build --no-cache
docker-compose up -d --force-recreate

---

Code Style

Go

• Use gofmt and goimports before committing
• Follow standard Go naming conventions
• Add comments for exported functions
• Keep functions small and focused

# Format code
gofmt -w .
goimports -w .

# Lint
golangci-lint run

TypeScript/React

• Use Prettier for formatting
• Follow ESLint rules
• Use TypeScript strict mode
• Prefer functional components with hooks

# Format code
npm run format

# Lint
npm run lint

---

Debugging

Server Debug Mode

./redflag-server --log-level debug

Agent Debug Mode

./redflag-agent --log-level debug

Web Debug Mode

npm run dev  # Includes source maps and hot reload

Database Queries

# Connect to PostgreSQL
docker exec -it redflag-postgres psql -U redflag -d redflag

# Common queries
SELECT * FROM agents;
SELECT * FROM registration_tokens;
SELECT * FROM agent_commands WHERE status = 'pending';

---

Common Development Tasks

Reset Everything

docker-compose down -v  # Destroy all data
make clean              # Clean build artifacts
rm -rf aggregator-agent/cache/
docker-compose up -d    # Start fresh

Update Dependencies

# Go modules
cd aggregator-server && go get -u ./...
cd aggregator-agent && go get -u ./...

# npm packages
cd aggregator-web && npm update

Generate Mock Data

# Create test registration token
curl -X POST http://localhost:8080/api/v1/admin/registration-tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"label": "Test Token", "max_seats": 10}'

---

Release Process

1. Update version in aggregator-agent/cmd/agent/main.go
2. Update CHANGELOG.md
3. Run full test suite
4. Build release binaries
5. Create git tag
6. Push to GitHub

# Build release binaries
make build-all

# Create tag
git tag -a v0.1.17 -m "Release v0.1.17"
git push origin v0.1.17

---

Troubleshooting

"Permission denied" on Linux

# Give execute permissions
chmod +x redflag-agent
chmod +x redflag-server

Database connection issues

# Check if PostgreSQL is running
docker ps | grep postgres

# Check connection
psql -h localhost -U redflag -d redflag

Port already in use

# Find process using port 8080
lsof -i :8080
kill -9 <PID>

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

Keep commits small and focused. Write clear commit messages.