Development Guide

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendix

Introduction

This development guide is designed for Sparrow project contributors and extension developers, providing systematic guidance from environment setup, code standards, contribution process to refactoring plans, technical debt handling, and version evolution strategies. The document also covers code review standards, testing requirements, documentation writing standards, and how to participate in open source contributions, submit Issues and Pull Requests, and participate in community discussions. Finally, it provides development tool recommendations, IDE configuration suggestions, and debugging tips to help teams collaborate efficiently and continuously deliver high-quality code.

Project Structure

Sparrow adopts a modular and layered architecture to organize code, with core directories including:

• bootstrap: Application startup, container, configuration loading, and service lifecycle management
• config: Centralized configuration model and default values
• logger: Unified logging encapsulation
• entity/usecase: Domain models and repository interfaces
• persistence/repo: Multiple storage implementations (memory, Badger, PostgreSQL, Redis, etc.)
• messaging: Event bus and stream processing (NATS JetStream)
• tasks: Task scheduling abstraction
• auth: Authentication token model
• utils: General utility functions
• pkg/adapter/http: HTTP adapter layer (routing, middleware, handlers)
• pkg/ws: WebSocket support
• .trae/documents: Documentation and solution descriptions
• .qoder/agents/skills: Agents and skills (optional extensions)

Core Components

• Application Startup and Lifecycle: Responsible for configuration loading, logging initialization, HTTP service startup, subprocess and subscriber graceful shutdown, exponential backoff retry mechanism
• IoC Container: Supports anonymous and named dependency registration and resolution, provides instance caching and dependency injection capabilities
• Configuration System: Centrally defines application, server, CORS, logging, NATS, SQL, Redis, Badger, RabbitMQ, Kafka, Casbin and other configuration items and default values
• Logging System: Unified logging encapsulation, supports development and production mode switching, rolling logs and level control
• Domain and Repository: Entity interface constraints, repository base class and general query conditions/sort fields, memory repository implementation
• Messaging and Events: Event stream Hub, subscribers, JetStream publish/subscribe
• Task Scheduling: Task interface, scheduler interface, task status and scheduling type
• Authentication: Token structure (access token, refresh token, scope, expiration interval)
• Utility Functions: String, naming style conversion, time parsing, numeric conversion, etc.

Architecture Overview

Sparrow adopts a layered design of "application layer + configuration/logging + domain/repository + messaging/tasks", achieving loose coupling dependency injection through IoC container; when the application starts, it initializes Gin HTTP engine, NATS connection and event stream Hub, then starts subprocesses and subscribers, providing graceful shutdown and retry mechanism; configuration system loads default values and environment variables through Viper, logging system supports development and production mode differences.

Detailed Component Analysis

Application Startup and Lifecycle (App)

Responsibilities: Load configuration, create logger, initialize Gin engine, register container, start subprocesses and subscribers, provide graceful shutdown and exponential backoff retry

Key Points:

• When subprocess startup fails, it enters retry queue with exponential backoff and limits maximum retry count
• HTTP server startup and signal listening, supports graceful shutdown
• Event stream Hub and subscriber registration and cleanup

IoC Container

Responsibilities: Register anonymous/named providers, resolve dependencies and cache instances, support resolution by name

Design Points:

• Key structure distinguishes type and name
• Resolve prioritizes named match, otherwise falls back to anonymous
• Supports automatic resolution of constructor parameters

Configuration System

Responsibilities: Centrally define application, server, CORS, logging, NATS, SQL, Redis, Badger, RabbitMQ, Kafka, Casbin and other configuration items and default values

Usage: Load default values and environment variables through Viper, called by App during application startup

Logging System

Responsibilities: Unified logging encapsulation, supports development and production modes, rolling logs and level control

Usage: Create Logger instance during App initialization, used by various modules

Domain and Repository

Entity Interface: Unified ID, creation/update time access

Repository Base Class: Provides general CRUD, pagination, conditional queries, sort fields and other interfaces and default implementations

Memory Repository: Lock-based concurrent safe implementation, supports reflection setting of time fields, conditional queries and random sampling

Messaging and Events

Responsibilities: Event stream Hub encapsulates subscribers, supports startup and graceful shutdown; subscribers handle events

Key Points: Create JetStream Bus through NATS connection, supports registering handlers by aggregate type and event type

Task Scheduling

Responsibilities: Define task and scheduler interfaces, support immediate, scheduled, recurring tasks, provide status management and retry control

Key Points: Task info structure includes scheduling time, status, retry count, error message, TTL, etc.

Authentication

Responsibilities: Define data structures for access token, refresh token, authorization scope and expiration interval

Utility Functions

Responsibilities: Provide string, naming style (snake/pascal/camel/kebab), plural, time parsing, numeric conversion and other general utilities

Dependency Analysis

Language and Tools: Go 1.25, use golangci-lint for static checking, Makefile provides common commands

External Dependencies: NATS, Redis, PostgreSQL, MongoDB, Casbin, Gin, Zap, Viper, Testify, OpenTelemetry, etc.

Dependency Injection: Implement IoC through self-developed Container, reduce external container dependencies

Logging and Configuration: Unified Logger package and Config module, ensure cross-module consistency

Performance Considerations

• Logging Performance: Enable rolling logs and level control in production mode, avoid excessive output
• Repository Performance: Memory repository suitable for testing scenarios; production recommends using PostgreSQL/Redis/Badger and other persistent storage, pay attention to batch operations and index design
• Event Bus: JetStream publish/subscribe needs reasonable stream configuration and consumer group settings to avoid message backlog
• Task Scheduling: Choose concurrent or sequential execution mode based on business requirements, reasonably set maximum concurrency and retry strategy
• Dependency Injection: Minimize reflection usage when container resolves dependencies, prioritize named registration to improve maintainability

Troubleshooting Guide

• Configuration Loading Failure: Check configuration files and environment variables, confirm default values are correct
• Logging Abnormal: Confirm logging mode and output path, pay attention to rolling log configuration in production mode
• Event Subscription Failure: Check NATS connection, stream configuration and consumer group settings
• Repository Error: Verify entity ID, time field settings and concurrency safety
• Task Scheduling Abnormal: Check task status and retry count, check callbacks and timeout settings

Conclusion

Sparrow provides a stable foundation for distributed and event-driven scenarios through clear layered architecture, unified logging and configuration, flexible IoC container and event bus. It is recommended to continue improving test coverage, optimizing error handling and logging, unifying naming and export strategies in subsequent versions, and continuously improving the performance and maintainability of task scheduling and repository implementations.

Appendix

Development Environment Setup

• Install Go 1.25
• Install golangci-lint
• Prepare NATS, PostgreSQL, Redis, MongoDB and other dependency services (can be started through Docker Compose)
• Use Makefile common commands: build, run, test, format, code check, Docker build and run

Code Standards

• Naming Conventions: Unified use of camelCase naming; exported structs and methods maintain consistency
• Error Handling: Use error wrapping and unified error types, provide context information
• Logging: Unified use of Logger package, avoid directly creating new logger instances
• Dependency Injection: Prioritize named registration, reduce reflection usage
• Testing: Supplement unit tests for key components, cover event bus, repository and utility functions

Contribution Process

• Submit Issue: Describe problem background, reproduction steps, expected behavior and actual behavior
• Submit PR: Follow code standards and testing requirements, provide change description and impact assessment
• Code Review: Focus on error handling, logging, performance and maintainability
• Community Discussion: Discuss design plans and refactoring plans through Issue/PR

Version Evolution

• Semantic Versioning: Follow semantic version control, major changes and breaking updates upgrade major version
• Technical Debt: Regularly review refactoring points in TODO.md, gradually optimize event bus, repository and error handling
• Migration and Compatibility: Provide migration guides and backward compatibility strategies, ensure smooth upgrades

Development Tools

• Editor: VSCode or GoLand, enable gofmt, golines, golangci-lint plugins
• Debugging: Use Delve for breakpoint debugging, combine with logging to locate problems
• Containerization: Use Docker and docker-compose to quickly build local dependency environments
• Documentation: Write API and architecture descriptions in Markdown, keep synchronized with code updates