spore-registry/docs/ARCHITECTURE.md

Architecture

Overview

The refactored code follows a clean architecture pattern with clear separation of concerns:

1. Models (internal/models/)

• Contains all data structures and types
• FirmwareMetadata, FirmwareRecord, GroupedFirmware, etc.
• Pure data structures with JSON tags

2. Config (internal/config/)

• Configuration management
• Environment variable handling
• Default values and validation

3. Database (internal/database/)

• Database connection management
• Table creation and schema management
• Connection lifecycle handling

4. Repository (internal/repository/)

• Data access layer
• Database operations (CRUD)
• SQL query management
• Data mapping between database and models

5. Storage (internal/storage/)

• File system operations
• Firmware binary storage
• File path management
• File existence checks

6. Service (internal/service/)

• Business logic layer
• Orchestrates repository and storage operations
• Data validation and processing
• Version comparison logic

7. Handlers (internal/handlers/)

• HTTP request handling
• Request/response processing
• Error handling and status codes
• Input validation

8. App (internal/app/)

• Application initialization
• Dependency injection
• Route setup
• Server configuration

9. Main (main.go)

• Entry point
• Minimal and focused
• Error handling and graceful shutdown

Environment Variables

• PORT: Server port (default: 3002)
• DB_PATH: Database file path (default: ./registry/registry.db)
• REGISTRY_PATH: Firmware storage directory (default: registry)
• MAX_UPLOAD_SIZE: Maximum upload size in bytes (default: 32MB)

API Endpoints

All API endpoints remain the same:

• POST /firmware - Upload firmware
• GET /firmware - List firmware (with optional filters)
• GET /firmware/{name}/{version} - Download firmware
• PUT /firmware/{name}/{version} - Update firmware metadata
• GET /health - Health check

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test
go test -run TestStoreFirmwareMetadata