# maragudk/goqite architecture

> Architecture diagram of the GitHub repository maragudk/goqite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maragudk/goqite
- Repository: https://github.com/maragudk/goqite

## Overview

##### Main Components
- Core Queue Library (goqite): Represents the primary functionality for message queuing. This includes the API methods for sending, receiving, deleting, and extending message timeouts.
- Job Runner (jobs): An abstraction layer built on top of the queue for executing background tasks. It registers jobs (like printing a message) and polls the queue.
- HTTP Handler: A lightweight HTTP interface is provided in the "http" directory to allow for operations via RESTful calls.
- Persistence Layer (SQLite): This component underpins message persistence. It is accessed through a user-supplied SQLite driver, and the schema is defined in schema.sql.
- Internal Utility Modules:
- SQL Utilities (internal/sql): Handling transaction support, ensuring database operations are correctly wrapped.
- Testing utilities (internal/testing): Contains test schemas and helper functions.
- Documentation/Examples: While not part of runtime logic, the docs (including example usage for queues and jobs) are essential to understanding how to integrate with the library.

- The HTTP Handler should be connected to the Core Queue, demonstrating that API requests (HTTP calls) are translated to queue operations.
- From the client side perspective (e.g., example applications or service integrations), represent external components that initialize and interact with the library, passing in the SQLite connection.

##### Architectural Patterns and Design Principles
- Modular Design: Detailing clear separation between the core queue, job runner, and HTTP handler.
- Clean API Abstraction: Emphasize how the library offers a straightforward API to send, receive, extend, and delete messages.
- Dependency Injection: Note that the design allows users to “bring their own” SQLite driver and database connection.
- Extensibility: Highlight that users can create multiple queues (via names) with custom job handlers.

##### Technologies and Frameworks
- Go’s standard library (context, database/sql, etc.)
- SQLite (as the persistence engine)
- User-supplied SQLite driver (such as github.com/mattn/go-sqlite3)
- Testing and benchmarking utilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client/External Application"]:::client

    %% Library API Layer
    subgraph "Library API Layer"
        core["Core Queue Library (goqite)"]:::core
        init["Initialization / Setup"]:::setup
    end

    %% HTTP Integration Layer
    subgraph "HTTP Integration Layer"
        http["HTTP Integration/Handler"]:::handler
    end

    %% Background Job Layer
    subgraph "Background Job Layer"
        jobs["Job Runner Abstraction"]:::job
    end

    %% Persistence / Database Layer
    subgraph "Persistence Layer"
        db["SQLite Database (Persistence Layer)"]:::database
    end

    %% Internal Modules
    subgraph "Internal Modules"
        sqlu["Internal SQL Utilities"]:::utility
        test["Testing Utilities"]:::testing
        docs["Documentation/Examples"]:::docs
    end

    %% Data Flow Connections
    Client -->|"callsAPI"| http
    Client -->|"callsAPI"| core

    http -->|"translatesRESTtoAPI"| core

    core -->|"CRUDoperations"| db
    init -->|"SetupSchema"| db

    jobs -->|"dequeueExecute"| core

    core -->|"usesSQLutils"| sqlu
    core -->|"testingHooks"| test

    %% Click Events
    click core "https://github.com/maragudk/goqite/blob/main/goqite.go"
    click jobs "https://github.com/maragudk/goqite/blob/main/jobs/runner.go"
    click http "https://github.com/maragudk/goqite/blob/main/http/handler.go"
    click db "https://github.com/maragudk/goqite/blob/main/schema.sql"
    click sqlu "https://github.com/maragudk/goqite/blob/main/internal/sql/tx.go"
    click test "https://github.com/maragudk/goqite/blob/main/internal/testing/testing.go"
    click docs "https://github.com/maragudk/goqite/tree/main/docs/"

    %% Styles
    classDef client fill:#e6e6ff,stroke:#333,stroke-width:2px;
    classDef core fill:#f9c2ff,stroke:#333,stroke-width:2px;
    classDef setup fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef handler fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef job fill:#c2f9c2,stroke:#333,stroke-width:2px;
    classDef database fill:#fff3b0,stroke:#333,stroke-width:2px;
    classDef utility fill:#cde6f7,stroke:#333,stroke-width:2px;
    classDef testing fill:#f7c2c2,stroke:#333,stroke-width:2px;
    classDef docs fill:#d2f7d2,stroke:#333,stroke-width:2px;
```
