# tirthpatell/threads-go architecture

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

- Interactive diagram: https://gitdiagram.com/tirthpatell/threads-go
- Repository: https://github.com/tirthpatell/threads-go

## Overview

##### Project type and purpose
- This is an open-source Go client library (SDK) for the Meta Threads API. Its purpose is to provide Go applications with a type-safe, fully-featured interface covering all API endpoints, OAuth2 authentication flows, rate limiting, error handling, pagination, and utilities for iterating through large result sets.

##### File structure
- Top-level Go source files (auth.go, client.go, http_client.go, etc.) implement the core client, authentication, HTTP transport, rate limiter, and error handling.
- interfaces.go defines abstractions for mocking/testing.
- container_builder.go wires up dependencies (HTTP client, token store, backoff).
- endpoint modules: posts_*.go, users.go, replies.go, insights.go, search.go, location.go.
- client_utils.go, constants.go, pagination.go, validation.go provide shared constants, request builders, pagination helpers, and input validation.
- examples/ shows how to consume the client in various scenarios.
- tests/integration/ exercises end-to-end against the real API.
- Configuration is defined in types.go (Config struct) and environment variable loaders in client.go.

##### README for additional insights
- Describes OAuth2 flows (GetAuthURL, ExchangeCodeForToken, GetLongLivedToken).
- Highlights intelligent rate limiting with exponential backoff.
- Notes comprehensive error types (AuthenticationError, RateLimitError, ValidationError, etc.).
- Emphasizes thread-safety and concurrent use.
- Mentions iterators for automatic pagination across Posts, Replies, Search results.

a. Main components
- SDK Interface Layer: public client API methods (.CreateTextPost, .GetUser, .ReplyToPost, iterators).
- Core Client: the Client struct holding Config, HTTPClient, AuthManager, RateLimiter.
- AuthManager: implements OAuth2 code exchange, token refresh, token storage.
- HTTP Transport: wraps net/http, injects auth headers, rate-limit middleware.
- RateLimiter: enforces request pacing, exponential backoff.
- Error Handler: parses HTTP responses into typed errors.
- Pagination & Iterator modules: manage cursor/offset and auto-fetch subsequent pages.
- Utility Modules: constants, validation, request/response models (types.go, types_ids.go).
- External Services: Threads API endpoints, OAuth2 token endpoint.
- Examples & Tests: sample consumers and integration test harness.

b. Relationships and interactions
- User Code → SDK Interface → Core Client
- Core Client calls AuthManager to get/access tokens
- Core Client delegates requests to HTTP Transport
- HTTP Transport applies RateLimiter, sends request to external Threads API
- Response flows back through Error Handler → parsed into domain models → returned to user
- Iterator modules request multiple pages via repeated HTTP Transport calls
- Config and environment loaders feed into Core Client on initialization
- Integration Tests simulate user code and verify end-to-end flows

c. Architectural patterns & design principles
- Dependency Injection via container_builder.go for HTTP client, auth, rate limiter
- Interface abstraction (interfaces.go) for mocking and unit testing
- Modular separation by endpoint/domain (posts, users, replies, insights, search, location)
- Middleware pattern in HTTP transport for auth header injection and rate limiting
- Iterator pattern for pagination
- Fail-fast validation and typed error handling

d. Key technologies & libraries
- Go standard library (net/http, context, encoding/json)
- OAuth2 protocol (custom implementation in auth.go)
- Exponential backoff and rate-limit logic (ratelimit.go)
- Go modules for dependency management (go.mod)
- CI workflows (.github/workflows) and integration test suite

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef core fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef util fill:#DFFFD0,stroke:#000,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef middleware fill:#E0FFE0,stroke:#000,stroke-width:1px
    classDef test fill:#E0E0E0,stroke:#000,stroke-width:1px

    subgraph "User"
        UserApp[/User Application/]:::external
    end

    subgraph "SDK Interface Layer"
        PostsCreate["posts_create.go"]:::core
        PostsRead["posts_read.go"]:::core
        PostsDelete["posts_delete.go"]:::core
        PostsReplies["posts_replies.go"]:::core
        RepliesFile["replies.go"]:::core
        UsersFile["users.go"]:::core
        InsightsFile["insights.go"]:::core
        SearchFile["search.go"]:::core
        LocationFile["location.go"]:::core
        ClientAPI["client.go"]:::core
    end

    subgraph "Core Client"
        ClientCore["Client struct"]:::core
        TypesFile["types.go"]:::core
    end

    subgraph "Auth Manager"
        AuthManager["auth.go"]:::core
    end

    subgraph "Middleware & Transport"
        HTTPTransport["http_client.go"]:::middleware
        RateLimiter["ratelimit.go"]:::middleware
        ErrorHandler["errors.go"]:::middleware
    end

    subgraph "Pagination & Iterators"
        Pagination["pagination.go"]:::util
    end

    subgraph "Utilities"
        Constants["constants.go"]:::util
        Utils["client_utils.go"]:::util
        Validation["validation.go"]:::util
        TypesIDs["types_ids.go"]:::util
    end

    subgraph "Dependency Injection"
        Container["container_builder.go"]:::core
    end

    subgraph "Interface Abstractions"
        Interfaces["interfaces.go"]:::core
    end

    subgraph "Examples & Tests"
        ExamplesDir["examples/"]:::test
        TestsDir["tests/integration/"]:::test
    end

    subgraph "External Services"
        ThreadsAPI[(Threads API)]:::external
        OAuthServer[(OAuth2 Server)]:::external
    end

    UserApp --> ClientAPI
    ClientAPI --> ClientCore
    PostsCreate --> ClientCore
    PostsRead --> ClientCore
    PostsDelete --> ClientCore
    PostsReplies --> ClientCore
    RepliesFile --> ClientCore
    UsersFile --> ClientCore
    InsightsFile --> ClientCore
    SearchFile --> ClientCore
    LocationFile --> ClientCore

    ClientCore --> AuthManager
    ClientCore --> HTTPTransport
    HTTPTransport --> RateLimiter
    HTTPTransport --> ErrorHandler
    HTTPTransport --> ThreadsAPI
    AuthManager --> OAuthServer
    Pagination --> HTTPTransport

    Container --> ClientCore
    Container --> AuthManager
    Container --> HTTPTransport
    Container --> RateLimiter

    Interfaces --> ClientCore

    ExamplesDir --> UserApp
    TestsDir --> UserApp

    click PostsCreate "https://github.com/tirthpatell/threads-go/blob/main/posts_create.go"
    click PostsRead "https://github.com/tirthpatell/threads-go/blob/main/posts_read.go"
    click PostsDelete "https://github.com/tirthpatell/threads-go/blob/main/posts_delete.go"
    click PostsReplies "https://github.com/tirthpatell/threads-go/blob/main/posts_replies.go"
    click RepliesFile "https://github.com/tirthpatell/threads-go/blob/main/replies.go"
    click UsersFile "https://github.com/tirthpatell/threads-go/blob/main/users.go"
    click InsightsFile "https://github.com/tirthpatell/threads-go/blob/main/insights.go"
    click SearchFile "https://github.com/tirthpatell/threads-go/blob/main/search.go"
    click LocationFile "https://github.com/tirthpatell/threads-go/blob/main/location.go"
    click ClientAPI "https://github.com/tirthpatell/threads-go/blob/main/client.go"
    click TypesFile "https://github.com/tirthpatell/threads-go/blob/main/types.go"
    click AuthManager "https://github.com/tirthpatell/threads-go/blob/main/auth.go"
    click HTTPTransport "https://github.com/tirthpatell/threads-go/blob/main/http_client.go"
    click RateLimiter "https://github.com/tirthpatell/threads-go/blob/main/ratelimit.go"
    click ErrorHandler "https://github.com/tirthpatell/threads-go/blob/main/errors.go"
    click Pagination "https://github.com/tirthpatell/threads-go/blob/main/pagination.go"
    click Constants "https://github.com/tirthpatell/threads-go/blob/main/constants.go"
    click Utils "https://github.com/tirthpatell/threads-go/blob/main/client_utils.go"
    click Validation "https://github.com/tirthpatell/threads-go/blob/main/validation.go"
    click TypesIDs "https://github.com/tirthpatell/threads-go/blob/main/types_ids.go"
    click Container "https://github.com/tirthpatell/threads-go/blob/main/container_builder.go"
    click Interfaces "https://github.com/tirthpatell/threads-go/blob/main/interfaces.go"
    click ExamplesDir "https://github.com/tirthpatell/threads-go/tree/main/examples/"
    click TestsDir "https://github.com/tirthpatell/threads-go/tree/main/tests/integration/"
```
