siriusscan--sirius/documentation/dev/README.developer-guide.md

title, description, template, version, last_updated, author, tags, categories, difficulty, prerequisites, related_docs, dependencies, llm_context, search_keywords

title	description	template	version	last_updated	author	tags	categories	difficulty	prerequisites	related_docs	dependencies	llm_context	search_keywords
Sirius Developer Guide	Complete guide for developers working on Sirius, including environment setup, development workflows, and best practices.	TEMPLATE.guide	1.0.0	2025-01-03	Development Team	development guide workflow docker environment	development guide	beginner	docker git nodejs go	README.development.md README.docker-architecture.md README.container-testing.md	scripts/switch-env.sh docker-compose.yaml docker-compose.dev.yaml docker-compose.prod.yaml	high	developer guide development workflow environment switching docker development hot reloading development setup

Sirius Developer Guide

Overview

This guide provides everything you need to know to develop effectively on the Sirius project. Whether you're working on the UI, API, engine, or any other component, this guide will help you get up and running quickly.

Quick Start

# Clone the repository
git clone https://github.com/SiriusScan/Sirius.git
cd Sirius

# Start development environment
./scripts/switch-env.sh dev

# Access the application
open http://localhost:3000

Development Environments

Sirius supports three distinct development environments, each optimized for different use cases:

🚀 Development Mode (Recommended)

Best for: UI/API development, testing, most development tasks

./scripts/switch-env.sh dev

Features:

• Hot reloading for instant code changes
• Volume mounts for live code updates
• Development-optimized builds
• SQLite database for faster development
• Debug logging enabled

What's Running:

• UI: npm run dev (Next.js development server)
• API: Go development mode with live reloading
• Engine: Development mode with volume mounts

🏭 Production Mode

Best for: Testing production builds, performance testing, pre-deployment validation

./scripts/switch-env.sh prod

Features:

• Optimized production builds
• PostgreSQL database
• Production authentication
• Performance optimizations
• Security hardening

What's Running:

• UI: npm start (Next.js production server)
• API: Pre-built Go binary
• Engine: Production-optimized runtime

⚙️ Base Mode

Best for: Standard operations, CI/CD, basic testing

./scripts/switch-env.sh base

Features:

• Default configuration
• Balanced performance
• Standard resource allocation
• Core functionality only

Environment Switching

The scripts/switch-env.sh script handles seamless switching between environments:

# Switch to development
./scripts/switch-env.sh dev

# Switch to production
./scripts/switch-env.sh prod

# Switch to base
./scripts/switch-env.sh base

What the script does:

1. Stops all running containers
2. Removes old images to prevent cache conflicts
3. Builds the appropriate environment with correct build targets
4. Starts all services
5. Shows container status and access URLs

Development Workflow

Daily Development

1. Start your day:

   ./scripts/switch-env.sh dev
   

2. Make your changes:

   • Edit UI code in sirius-ui/src/
   • Edit API code in sirius-api/
   • Edit engine code in sirius-engine/

3. See changes instantly:

   • UI changes appear immediately (hot reloading)
   • API changes require container restart
   • Engine changes require container restart

4. Test your changes:

   # Check container status
   docker compose ps
   
   # View logs
   docker compose logs sirius-ui
   docker compose logs sirius-api
   

Testing Production Builds

1. Switch to production mode:

   ./scripts/switch-env.sh prod
   

2. Test your changes:

   • Verify UI renders correctly
   • Test API endpoints
   • Check performance characteristics

3. Switch back to development:

   ./scripts/switch-env.sh dev
   

Working with Different Components

Frontend Development (UI)

# Start development mode
./scripts/switch-env.sh dev

# Make changes to React components
# Changes appear instantly in browser

# Test production build
./scripts/switch-env.sh prod

Backend Development (API)

# Start development mode
./scripts/switch-env.sh dev

# Make changes to Go code
# Restart API container to see changes
docker compose restart sirius-api

# Check API logs
docker compose logs sirius-api -f

Engine Development

# Start development mode
./scripts/switch-env.sh dev

# Make changes to engine code
# Restart engine container to see changes
docker compose restart sirius-engine

# Check engine logs
docker compose logs sirius-engine -f

Project Structure

Sirius/
├── sirius-ui/                    # Next.js frontend
│   ├── src/                     # React components and pages
│   ├── Dockerfile               # Multi-stage build (dev/prod)
│   ├── start-dev.sh            # Development startup script
│   └── start-prod.sh           # Production startup script
├── sirius-api/                  # Go REST API
│   ├── cmd/                    # API entry point
│   ├── internal/               # Internal API code
│   └── Dockerfile              # Multi-stage build (dev/runner)
├── sirius-engine/              # Multi-service engine
│   ├── cmd/                    # Engine entry point
│   ├── internal/               # Internal engine code
│   └── Dockerfile              # Multi-stage build (dev/runtime)
├── docker-compose.yaml         # Base configuration
├── docker-compose.dev.yaml     # Development overrides
├── docker-compose.prod.yaml    # Production overrides
└── scripts/
    └── switch-env.sh           # Environment switching script

Docker Architecture

Multi-Stage Builds

Each service uses multi-stage Dockerfiles to optimize for different environments:

sirius-ui:

• development: Full dev environment with hot reloading
• production: Optimized production build

sirius-api:

• development: Go development with live reloading
• runner: Pre-built Go binary for production

sirius-engine:

• development: Full development environment
• runtime: Production-optimized runtime

Image Tagging Strategy

• Development: sirius-sirius-ui:dev
• Production: sirius-sirius-ui:prod
• Base: sirius-sirius-ui:latest

This prevents Docker cache conflicts when switching environments.

CI/CD Integration

Pre-commit Validation

Purpose: Fast validation to catch obvious issues before commit

Duration: ~30 seconds

What's Tested:

• Docker Compose configuration validation
• Documentation linting
• Basic syntax checks
• Code formatting

Commands:

# Pre-commit validation (automatic)
git commit  # Runs quick validation automatically

# Manual validation
cd testing/container-testing
make build-all          # Validate all Docker Compose configs
make lint-docs-quick    # Quick documentation checks

CI/CD Pipeline

Purpose: Comprehensive testing of all changes

Duration: ~5-10 minutes

What's Tested:

• Docker container builds (all services)
• Service health checks
• Integration testing
• Cross-service communication
• Production build validation

Triggers:

• Pull requests to main branch
• Pushes to main branch
• Hotfix pushes

Local Testing

Purpose: Manual testing during development

Available Commands:

# Full test suite
cd testing/container-testing
make test-all

# Individual tests
make test-build          # Test Docker builds
make test-health         # Test service health
make test-integration    # Test integration

# Quick validation
make build-all           # Validate configs
make lint-docs-quick     # Quick docs check

Testing Strategy

Scenario	Pre-commit	CI/CD	Local Testing
Feature Development	✅ Quick validation	❌ No	✅ Full testing
Pull Request	✅ Quick validation	✅ Full testing	✅ Full testing
Main Branch	✅ Quick validation	✅ Full testing	✅ Full testing
Documentation	✅ Quick validation	❌ No	✅ Full testing

Common Tasks

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs sirius-ui -f
docker compose logs sirius-api -f
docker compose logs sirius-engine -f

Accessing Containers

# Open shell in container
docker compose exec sirius-ui sh
docker compose exec sirius-api sh
docker compose exec sirius-engine sh

Restarting Services

# Restart specific service
docker compose restart sirius-ui

# Restart all services
docker compose restart

Checking Service Health

# View container status
docker compose ps

# Check health endpoints
curl http://localhost:3000/api/health
curl http://localhost:9001/api/v1/health
curl http://localhost:5174/health

Database Access

# Development (SQLite)
docker compose exec sirius-ui ls -la /app/dev.db

# Production (PostgreSQL)
docker compose exec sirius-postgres psql -U postgres -d sirius

Troubleshooting

Environment Switching Issues

Problem: Wrong environment running despite switching Solution: The script automatically handles this, but if issues persist:

# Force clean rebuild
docker system prune -f
./scripts/switch-env.sh dev

Hot Reloading Not Working

Problem: UI changes not appearing instantly Solution: Ensure you're in development mode:

./scripts/switch-env.sh dev
# Check it's running: docker compose exec sirius-ui ps aux

Services Not Starting

Problem: Containers failing to start Solution: Check logs and restart:

docker compose logs sirius-ui
docker compose restart sirius-ui

Port Conflicts

Problem: Port already in use Solution: Stop conflicting services:

# Check what's using the port
lsof -i :3000
lsof -i :9001

# Stop conflicting services
sudo kill -9 <PID>

Database Connection Issues

Problem: API can't connect to database Solution: Check database health:

# Check database status
docker compose ps sirius-postgres

# Check database logs
docker compose logs sirius-postgres

# Restart database
docker compose restart sirius-postgres

Best Practices

Development Workflow

1. Always start with development mode for new features
2. Test in production mode before committing
3. Use hot reloading for UI development
4. Check logs regularly to catch issues early
5. Switch environments to test different scenarios

Code Organization

1. Keep components focused and single-purpose
2. Use TypeScript for better type safety
3. Follow naming conventions consistently
4. Write tests for critical functionality
5. Document complex logic with comments

Docker Usage

1. Use the switch script instead of manual docker commands
2. Don't edit Docker Compose files directly unless necessary
3. Clean up unused images regularly
4. Monitor resource usage during development
5. Test in multiple environments before deploying

Git Workflow

1. Create feature branches for new work
2. Test thoroughly before merging
3. Write descriptive commit messages
4. Keep commits focused and atomic
5. Use pull requests for code review

Advanced Usage

Custom Environment Variables

Create a .env.local file for custom environment variables:

# .env.local
NODE_ENV=development
API_URL=http://localhost:9001
DEBUG=true

Volume Mounts for Live Development

For advanced development scenarios, you can mount local directories:

# Edit docker-compose.dev.yaml to add volume mounts
volumes:
  - ./sirius-ui/src:/app/src
  - ./sirius-api:/app

Debugging

Enable debug mode for more verbose logging:

# Set debug environment variable
export DEBUG=true
./scripts/switch-env.sh dev

Performance Testing

Use production mode for performance testing:

./scripts/switch-env.sh prod
# Run your performance tests

Getting Help

Documentation

• Docker Architecture - Detailed Docker setup
• Development Setup - Legacy development guide
• Container Testing - Testing procedures

Common Issues

• Check the troubleshooting section above
• Review container logs for error messages
• Ensure all prerequisites are installed
• Verify Docker is running properly

Support

• Create an issue on GitHub for bugs
• Use discussions for questions
• Check existing issues before creating new ones

---

This guide follows the Sirius Documentation Standard. For questions about documentation structure, see ABOUT.documentation.md.