Backend
Architecture

Architecture

Overview

The IBW Backend Service follows a layered architecture pattern with clear separation of concerns. This design ensures maintainability, testability, and scalability.

Architecture Layers

1. Handler Layer (internal/handlers/)

The handler layer is responsible for:

  • HTTP request/response handling
  • Request validation
  • Response formatting
  • Error handling

Key Handlers:

  • user_handler.go - User management endpoints
  • event_handler.go - Event management endpoints
  • quest_handler.go - Quest system endpoints
  • admin_handler.go - Admin operations
  • notification_handler.go - Notification endpoints
  • connection_handler.go - User connections
  • speaker_handler.go - Speaker management
  • conference_agenda_handler.go - Conference agenda
  • conference_attendee_handler.go - Conference attendance

2. Service Layer (internal/services/)

The service layer contains business logic:

  • Business rules and validations
  • Orchestration of multiple repositories
  • External API integrations
  • Complex business workflows

Key Services:

  • user_service.go - User business logic
  • event_service.go - Event business logic
  • quest_service.go - Quest system logic
  • notification_service.go - Notification logic
  • enrichment_service.go - Social media enrichment
  • telegram_service.go - Telegram integration
  • verification_service.go - Task verification

3. Repository Layer (internal/repositories/)

The repository layer provides data access abstraction:

  • Database queries
  • Data mapping
  • Transaction management
  • Cache integration

Key Repositories:

  • user_repository.go - User data access
  • event_repository.go - Event data access
  • quest_repository.go - Quest data access
  • notification_repository.go - Notification data access

4. Model Layer (internal/models/)

Domain models representing business entities:

  • user.go - User model
  • event.go - Event model
  • quest.go - Quest model
  • conference.go - Conference model
  • speaker.go - Speaker model
  • notification.go - Notification model

Dependency Injection

The application uses a Dependencies struct (internal/deps/deps.go) to manage all dependencies:

type Dependencies struct {
    DB                        *gorm.DB
    Cache                     *redisStorage.Storage
    Cfg                       *config.Config
    UserService               *services.UserService
    EventService              *services.EventService
    QuestService              *services.QuestService
    // ... more dependencies
}

This pattern:

  • Centralizes dependency management
  • Simplifies testing with mocks
  • Reduces coupling between components

Server Initialization

The server initialization flow (internal/server/server.go):

  1. Load Configuration - Environment variables and config
  2. Initialize Database - PostgreSQL connection via GORM
  3. Initialize Cache - Redis connection
  4. Create Repositories - Data access layer
  5. Create Services - Business logic layer
  6. Create Handlers - HTTP handlers
  7. Register Routes - API endpoints
  8. Start Workers - Background job workers

Middleware Stack

The application uses Fiber middleware for:

  1. Logging - Request/response logging
  2. Recovery - Panic recovery
  3. CORS - Cross-origin resource sharing
  4. Request ID - Unique request tracking
  5. Authentication - JWT and Telegram auth
  6. Rate Limiting - API rate limiting
  7. Admin Auth - Admin API key validation

Background Workers

Notification Job Worker

The NotificationJobService runs a background worker that:

  • Processes scheduled notifications
  • Sends bulk notifications
  • Tracks notification job status
  • Handles retries and failures

Started in server.go:

notificationJobService.StartWorker(ctx)

External Integrations

Telegram Integration

  • User authentication via Telegram bot
  • Notification sending
  • Group chat integration

Social Media APIs

  • Twitter: Profile and tweet fetching via Apify
  • LinkedIn: Profile data fetching
  • Enrichment: AI-powered social media enrichment

Storage Services

  • Azure Blob Storage: Image/video storage
  • Cloudflare R2: CDN and storage

AI Services

  • Azure OpenAI: Content generation and enrichment

Database

ORM: GORM

  • Database abstraction
  • Migration support
  • Relationship management

Connection Pooling

  • pgx connection pool
  • Configurable pool size
  • Connection health checks

Caching Strategy

Redis is used for:

  • Session storage
  • Rate limiting
  • Temporary data caching

Error Handling

Errors are handled at multiple levels:

  1. Repository Level: Database errors
  2. Service Level: Business logic errors
  3. Handler Level: HTTP error responses

Standard error response format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Logging

Uses Zerolog for structured logging:

  • Request/response logging
  • Error tracking
  • Performance monitoring
  • Debug information

Security

  1. Authentication:

    • JWT tokens for API access
    • Telegram bot tokens for user auth

  2. Authorization:

    • Admin API keys
    • Role-based access control

  3. Rate Limiting:

    • Per-endpoint rate limits
    • Redis-based rate limiting

  4. Input Validation:

    • Request validation
    • SQL injection prevention (via GORM)
    • XSS protection

Scalability Considerations

  1. Stateless Design: No server-side sessions
  2. Connection Pooling: Efficient database connections
  3. Caching: Redis for frequently accessed data
  4. Background Workers: Async job processing
  5. Horizontal Scaling: Can run multiple instances
OverviewAPI Endpoints