# gugilla-aakash/hakiapi architecture

> Architecture diagram of the GitHub repository gugilla-aakash/hakiapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gugilla-aakash/hakiapi
- Repository: https://github.com/gugilla-aakash/hakiapi

## Overview

#### Purpose and public entry points
HakiAPI is a Python 3.10+ SDK foundation for building resilient HTTP API clients, with bundled GitHub, Gmail, and Google Calendar clients. Public imports are organized through `hakiapi/__init__.py`; consumers either instantiate bundled clients or subclass the synchronous base client. Runnable usage references are `example_oauth.py` and `examples/example_github.py`.

#### Synchronous request core
`BaseAPIClient` centralizes session lifecycle, base-URL request routing, authentication attachment, timeouts, response parsing, raw-response access, and HTTP-status mapping. Endpoint methods in bundled or downstream clients should stay thin and call its verb methods.
- `hakiapi/core/base_client.py`
- `hakiapi/core/exceptions.py`
- `hakiapi/core/retry.py`

Flow: client endpoint → `_request()` → `requests.Session` with mounted `urllib3` retry adapters → external API → JSON/text or typed exception.

#### Authentication and OAuth boundary
Authentication strategies plug into `requests` through `AuthBase`: bearer, header/query API keys, HMAC signing, and OAuth-backed bearer injection. Google OAuth is separate from API transport: it manages browser authorization, localhost redirect capture, CSRF state validation, token exchange, persistence, and optional explicit refresh.
- `hakiapi/core/auth.py`
- `hakiapi/core/oauth/google.py`
- `hakiapi/core/oauth/token_store.py`

The OAuth integration touches Google authorization/token endpoints, the local browser, and a one-shot localhost HTTP server. Token persistence is local filesystem JSON with atomic replacement and restrictive permissions.

#### Resilience and failure semantics
Retries occur before final error mapping for retryable HTTP statuses and network failures. Typed exceptions provide a uniform boundary for application code across client implementations. A standalone, thread-safe circuit breaker wraps synchronous callables and transitions CLOSED → OPEN → HALF_OPEN to prevent repeated downstream failures.
- `hakiapi/core/retry.py`
- `hakiapi/core/exceptions.py`
- `hakiapi/core/circuit_breaker.py`

#### Pagination abstraction
A lazy paginator repeatedly invokes a client with `raw_response=True`, interprets response-specific item and continuation conventions, and yields items without making pagination part of each endpoint implementation. It supports Link-header and token-based styles used by the bundled services.
- `hakiapi/core/paginator.py`
- `hakiapi/core/base_client.py`

#### Async transport path
`AsyncBaseAPIClient` is an independent `asyncio`/`httpx` implementation, not a wrapper around the sync core. It recreates retry/backoff, typed exceptions, endpoint SSRF protections, disabled redirect following, response-size limits, and async context-manager cleanup. `httpx` is an optional runtime dependency.
- `hakiapi/core/async_base_client.py`
- `hakiapi/core/exceptions.py`

#### Bundled service adapters
Bundled clients specialize the common core with service URLs, authentication conventions, resource-oriented methods, and service-specific pagination. GitHub adds REST and GraphQL execution, including GraphQL payload-error detection; Gmail and Calendar expose resource groupings for their Google APIs.
- `hakiapi/clients/github.py`
- `hakiapi/clients/gmail.py`
- `hakiapi/clients/google_calendar.py`

External service boundaries are GitHub REST/GraphQL APIs, Gmail API, Google Calendar API, and Google OAuth endpoints. Packaging/release infrastructure is defined in `pyproject.toml` and `.github/workflows/release.yml`.

Main entry points: [`hakiapi/core/base_client.py`](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/base_client.py) (BaseAPIClient), [`hakiapi/__init__.py`](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/__init__.py) (Public SDK imports), [`hakiapi/core/oauth/google.py`](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/oauth/google.py) (Google OAuth flow), [`hakiapi/core/async_base_client.py`](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/async_base_client.py) (AsyncBaseAPIClient)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Client Core"]
  node_sync_client["BaseAPIClient<br/>sync HTTP client<br/>[base_client.py]"]
  node_async_client["AsyncBaseAPIClient<br/>async HTTP client"]
  node_paginator["Lazy paginator<br/>pagination<br/>[paginator.py]"]
end

subgraph group_auth["Auth &amp; Resilience"]
  node_retry["Retry policy<br/>resilience<br/>[retry.py]"]
  node_exceptions["Typed exceptions<br/>error boundary<br/>[exceptions.py]"]
  node_circuit_breaker["Circuit breaker<br/>resilience<br/>[circuit_breaker.py]"]
  node_auth_strategies["Auth strategies<br/>requests auth<br/>[auth.py]"]
  node_google_oauth["Google OAuth flow<br/>OAuth manager<br/>[google.py]"]
  node_token_store[("Token store<br/>local persistence<br/>[token_store.py]")]
end

subgraph group_clients["Bundled Clients"]
  node_github_client["GitHub client<br/>service adapter<br/>[github.py]"]
  node_gmail_client["Gmail client<br/>service adapter<br/>[gmail.py]"]
  node_calendar_client["Google Calendar client<br/>service adapter<br/>[google_calendar.py]"]
end

subgraph group_external["External Boundaries"]
  node_github_api{{"GitHub REST &amp; GraphQL<br/>external API"}}
  node_google_apis{{"Gmail &amp; Calendar APIs<br/>external APIs"}}
  node_google_oauth_endpoints{{"Google OAuth endpoints<br/>authorization service"}}
  node_local_oauth_interaction["Browser &amp; localhost callback<br/>local OAuth boundary"]
end

node_public_api["Public SDK imports<br/>package entry<br/>[__init__.py]"]

node_public_api -->|"exports"| node_sync_client
node_public_api -->|"exports"| node_async_client
node_public_api -->|"exports"| node_github_client
node_public_api -->|"exports"| node_gmail_client
node_public_api -->|"exports"| node_calendar_client
node_github_client -->|"specializes"| node_sync_client
node_gmail_client -->|"specializes"| node_sync_client
node_calendar_client -->|"specializes"| node_sync_client
node_sync_client -->|"attaches auth"| node_auth_strategies
node_sync_client -->|"mounts retry adapters"| node_retry
node_sync_client -->|"maps failures"| node_exceptions
node_async_client -->|"recreates backoff"| node_retry
node_async_client -->|"maps failures"| node_exceptions
node_paginator -->|"calls with raw response"| node_sync_client
node_google_oauth -->|"supplies OAuth bearer"| node_auth_strategies
node_google_oauth -->|"persists tokens"| node_token_store
node_google_oauth -->|"authorizes and exchanges"| node_google_oauth_endpoints
node_google_oauth -->|"uses redirect flow"| node_local_oauth_interaction
node_github_client -->|"REST and GraphQL requests"| node_github_api
node_gmail_client -->|"API requests"| node_google_apis
node_calendar_client -->|"API requests"| node_google_apis
node_circuit_breaker -.->|"wraps client calls"| node_sync_client

click node_public_api "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/__init__.py"
click node_sync_client "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/base_client.py"
click node_async_client "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/async_base_client.py"
click node_paginator "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/paginator.py"
click node_retry "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/retry.py"
click node_exceptions "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/exceptions.py"
click node_circuit_breaker "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/circuit_breaker.py"
click node_auth_strategies "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/auth.py"
click node_google_oauth "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/oauth/google.py"
click node_token_store "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/oauth/token_store.py"
click node_github_client "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/clients/github.py"
click node_gmail_client "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/clients/gmail.py"
click node_calendar_client "https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/clients/google_calendar.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sync_client,node_async_client,node_paginator toneBlue
class node_retry,node_exceptions,node_circuit_breaker,node_auth_strategies,node_google_oauth,node_token_store toneAmber
class node_github_client,node_gmail_client,node_calendar_client toneMint
class node_github_api,node_google_apis,node_google_oauth_endpoints,node_local_oauth_interaction toneRose
class node_public_api toneNeutral
```

## Components

### Client Core

Shared synchronous and asynchronous transport foundations.

- [BaseAPIClient](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/base_client.py): sync HTTP client · Centralizes session, routing, parsing, and status mapping. · `hakiapi/core/base_client.py`
- [AsyncBaseAPIClient](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/async_base_client.py): async HTTP client · Independent asyncio/httpx transport with safety controls. · `hakiapi/core/async_base_client.py`
- [Lazy paginator](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/paginator.py): pagination · Consumes raw responses and yields items across continuation styles. · `hakiapi/core/paginator.py`

### Auth & Resilience

Authentication, OAuth, and failure-control components.

- [Retry policy](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/retry.py): resilience · Configures retryable HTTP and network failure handling. · `hakiapi/core/retry.py`
- [Typed exceptions](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/exceptions.py): error boundary · Uniform application-facing HTTP failure mapping. · `hakiapi/core/exceptions.py`
- [Circuit breaker](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/circuit_breaker.py): resilience · Thread-safe CLOSED, OPEN, and HALF_OPEN callable guard. · `hakiapi/core/circuit_breaker.py`
- [Auth strategies](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/auth.py): requests auth · Bearer, API key, HMAC, and OAuth bearer attachment. · `hakiapi/core/auth.py`
- [Google OAuth flow](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/oauth/google.py): OAuth manager · Runs browser authorization, redirect validation, exchange, and refresh. · `hakiapi/core/oauth/google.py`
- [Token store](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/core/oauth/token_store.py): local persistence · Atomically persists restricted-permission token JSON. · `hakiapi/core/oauth/token_store.py`

### Bundled Clients

Service-specific API adapters.

- [GitHub client](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/clients/github.py): service adapter · Provides REST and GraphQL calls with GraphQL error detection. · `hakiapi/clients/github.py`
- [Gmail client](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/clients/gmail.py): service adapter · Exposes Gmail resource operations. · `hakiapi/clients/gmail.py`
- [Google Calendar client](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/clients/google_calendar.py): service adapter · Exposes Calendar resource operations. · `hakiapi/clients/google_calendar.py`

### External Boundaries

Remote services and local OAuth interactions.

- **GitHub REST & GraphQL**: external API
- **Gmail & Calendar APIs**: external APIs
- **Google OAuth endpoints**: authorization service
- **Browser & localhost callback**: local OAuth boundary · Browser authorization and one-shot localhost redirect capture.

### Other components

- [Public SDK imports](https://github.com/gugilla-aakash/hakiapi/blob/main/hakiapi/__init__.py): package entry · Exports the supported consumer-facing SDK surface. · `hakiapi/__init__.py`

## Connections

- Public SDK imports → BaseAPIClient: exports
- Public SDK imports → AsyncBaseAPIClient: exports
- Public SDK imports → GitHub client: exports
- Public SDK imports → Gmail client: exports
- Public SDK imports → Google Calendar client: exports
- GitHub client → BaseAPIClient: specializes
- Gmail client → BaseAPIClient: specializes
- Google Calendar client → BaseAPIClient: specializes
- BaseAPIClient → Auth strategies: attaches auth
- BaseAPIClient → Retry policy: mounts retry adapters
- BaseAPIClient → Typed exceptions: maps failures
- AsyncBaseAPIClient → Retry policy: recreates backoff
- AsyncBaseAPIClient → Typed exceptions: maps failures
- Lazy paginator → BaseAPIClient: calls with raw response
- Google OAuth flow → Auth strategies: supplies OAuth bearer
- Google OAuth flow → Token store: persists tokens
- Google OAuth flow → Google OAuth endpoints: authorizes and exchanges
- Google OAuth flow → Browser & localhost callback: uses redirect flow
- GitHub client → GitHub REST & GraphQL: REST and GraphQL requests
- Gmail client → Gmail & Calendar APIs: API requests
- Google Calendar client → Gmail & Calendar APIs: API requests
- Circuit breaker → BaseAPIClient: wraps client calls