# ozmap/ozmap-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/ozmap/ozmap-sdk
- Repository: https://github.com/ozmap/ozmap-sdk

## Overview

##### Project type and purpose
- This is a TypeScript-based SDK (an open-source client library) for interacting with the OZmap REST API. Its sole purpose is to provide a high-level, strongly-typed interface (CRUD, batch ops, filtering, pagination) to OZmap’s georeferenced data services.

##### File structure
Top-level:
- config files (.eslintrc, tsconfig.json, tsup.config.ts, GitHub workflows, Husky hooks)
- docs/ (one Markdown file per model for user reference)
- src/
– OZMapSDK.ts (the main SDK façade exposed to consumers)
– index.ts (public export)
– util/Api.ts (generic HTTP client wrapper)
– interface/ (TypeScript interfaces/DTOs for requests, responses, filter/pagination)
– proxy/
- Proxy.ts, ReadableProxy.ts, UpdatableProxy.ts, WritableProxy.ts (generic proxy classes encapsulating CRUD patterns)
- entities/ (one class per model that maps raw API JSON to a richer entity object)
Build & packaging: tsup, package.json, package-lock.json.

##### README for additional insights
- States features (CRUD, batch, pagination, filter) and usage examples.
- Shows two instantiation modes (login/password or API key).
- Describes direct-API methods via sdk.apiInstance.

##### How to model this
a. Main components
1. Client Application (TypeScript consumer code)
2. SDK Facade (OZMapSDK class)
3. HTTP Client Layer (util/Api.ts)
4. Proxy Layer (generic Proxy classes)
5. Entity Layer (proxy/entities/*)
6. Interface Layer (interface/model DTOs + filter/pagination)
7. External OZmap REST API
8. Build & Config (tsup, tsconfig, linters, CI workflows)
9. Documentation (docs/)
b. Relationships & interactions
- Client calls methods on OZMapSDK →
- internally selects correct Proxy (ReadableProxy, UpdatableProxy, etc.) →
- Proxy uses Api.ts to send HTTP requests to External OZmap API →
- API returns JSON →
- Api.ts hands raw JSON back to Proxy →
- Proxy instantiates Entities (mapping JSON to class instances) →
- SDK returns Entities or DTOs back to Client
- Build & Config sit aside to package and enforce code quality; docs/ support user understanding.
c. Architectural patterns & design principles
- Façade (OZMapSDK hides complexity)
- Proxy (abstracts remote calls behind common CRUD interfaces)
- Adapter/Mapper (entities map raw JSON to rich objects)
- Layered separation (interface → proxy → util → external service)
- Single Responsibility (each folder/class has one concern)
d. Key technologies/frameworks
- TypeScript (static typing, interfaces, generics)
- axios or fetch (inside util/Api.ts)
- tsup (build/bundle)
- ESLint, Prettier, Husky (quality & automation)
- GitHub Actions (CI for tests & publishing)

##### Detail & coverage
- Data-flow paths for all CRUD operations and for direct apiInstance calls.
- Do not omit the docs/ folder or CI config—they are essential for an open-source project.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    ClientApp["Client App"]:::client

    %% SDK Facade
    OZMapSDK["OZMapSDK (Facade)"]:::internal
    FacadeIndex["index.ts"]:::internal

    %% Interface Layer
    subgraph "Interface Layer"
        direction TB
        APIFilter["APIFilter.ts"]:::internal
        APISorter["APISorter.ts"]:::internal
        FilterOperator["FilterOperator.ts"]:::internal
        Pagination["Pagination.ts"]:::internal
        subgraph "Models"
            direction TB
            BoxModel["Box.ts"]:::internal
            UserModel["User.ts"]:::internal
            InterfaceModelIndex["index.ts"]:::internal
        end
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        direction TB
        ProxyBase["Proxy.ts"]:::internal
        ReadableProxy["ReadableProxy.ts"]:::internal
        UpdatableProxy["UpdatableProxy.ts"]:::internal
        WritableProxy["WritableProxy.ts"]:::internal
        ProxyIndex["index.ts"]:::internal
    end

    %% HTTP Client
    Api["HTTP Client (Api.ts)"]:::internal

    %% Entity Layer
    subgraph "Entities"
        direction TB
        BoxEntity["Box.ts"]:::internal
        UserEntity["User.ts"]:::internal
        EntitiesIndex["index.ts"]:::internal
    end

    %% External Service
    OZmapAPI["OZmap REST API"]:::external

    %% Supporting Tools
    subgraph "Supporting Tools"
        direction TB
        Docs["docs/"]:::support
        BuildConfig["Build & Config"]:::support
    end

    %% Data Flows
    ClientApp --> OZMapSDK
    OZMapSDK --> ProxyBase
    OZMapSDK --> FacadeIndex
    OZMapSDK --> APIFilter
    OZMapSDK --> APISorter
    OZMapSDK --> Pagination
    APIFilter --> ProxyBase
    APISorter --> ProxyBase
    Pagination --> ProxyBase
    ProxyBase --> ReadableProxy
    ProxyBase --> UpdatableProxy
    ProxyBase --> WritableProxy
    ReadableProxy --> ProxyIndex
    UpdatableProxy --> ProxyIndex
    WritableProxy --> ProxyIndex
    ProxyIndex --> Api
    Api --> OZmapAPI
    OZmapAPI --> Api
    Api --> ProxyIndex
    ProxyIndex --> BoxEntity
    ProxyIndex --> UserEntity
    BoxEntity --> EntitiesIndex
    UserEntity --> EntitiesIndex
    EntitiesIndex --> OZMapSDK
    OZMapSDK --> ClientApp
    Docs --> OZMapSDK
    BuildConfig --> OZMapSDK

    %% Click Events
    click OZMapSDK "https://github.com/ozmap/ozmap-sdk/blob/main/src/OZMapSDK.ts"
    click FacadeIndex "https://github.com/ozmap/ozmap-sdk/blob/main/src/index.ts"
    click APIFilter "https://github.com/ozmap/ozmap-sdk/blob/main/src/interface/APIFilter.ts"
    click APISorter "https://github.com/ozmap/ozmap-sdk/blob/main/src/interface/APISorter.ts"
    click FilterOperator "https://github.com/ozmap/ozmap-sdk/blob/main/src/interface/FilterOperator.ts"
    click Pagination "https://github.com/ozmap/ozmap-sdk/blob/main/src/interface/Pagination.ts"
    click BoxModel "https://github.com/ozmap/ozmap-sdk/blob/main/src/interface/model/Box.ts"
    click UserModel "https://github.com/ozmap/ozmap-sdk/blob/main/src/interface/model/User.ts"
    click InterfaceModelIndex "https://github.com/ozmap/ozmap-sdk/blob/main/src/interface/model/index.ts"
    click ProxyBase "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/Proxy.ts"
    click ReadableProxy "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/ReadableProxy.ts"
    click UpdatableProxy "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/UpdatableProxy.ts"
    click WritableProxy "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/WritableProxy.ts"
    click ProxyIndex "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/index.ts"
    click BoxEntity "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/entities/Box.ts"
    click UserEntity "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/entities/User.ts"
    click EntitiesIndex "https://github.com/ozmap/ozmap-sdk/blob/main/src/proxy/entities/index.ts"
    click Api "https://github.com/ozmap/ozmap-sdk/blob/main/src/util/Api.ts"
    click Docs "https://github.com/ozmap/ozmap-sdk/tree/main/docs/"
    click BuildConfig "https://github.com/ozmap/ozmap-sdk/blob/main/tsup.config.ts"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef external fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef support fill:#F2F3F4,stroke:#616A6B,color:#2C3E50
    classDef client fill:#FDEDEC,stroke:#922B21,color:#641E16
```
