# mizcausevic-dev/aeo-sdk-typescript architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/aeo-sdk-typescript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/aeo-sdk-typescript
- Repository: https://github.com/mizcausevic-dev/aeo-sdk-typescript

## Overview

#### Purpose and principal workflow

This TypeScript SDK implements AEO Protocol v0.1 document parsing, validation, serialization, claim queries, and well-known URL fetching. An application or developer using the SDK initiates the workflow by calling its public API: either provide a document to parse, or provide an origin to fetch from. In the fetch path, the SDK requests `/.well-known/aeo.json` and parses the response into a validated document.

#### Components

##### Public SDK and document operations
- **SDK public API** — `src/index.ts`: Exports the document schemas, types, parsing and query functions, fetch helpers, and SDK version for consumers.
- **Document model and operations** — `src/document.ts`: Defines strict Zod schemas and inferred types; parses and safely validates inputs, serializes documents, and lists or finds claims.

##### Discovery and validation dependencies
- **Well-known HTTP client** — `src/client.ts`: Builds the discovery URL, fetches it with an `Accept` header and timeout/abort handling, checks the response, and passes its text to document parsing.
- **Zod** — null repository path (external dependency): Supplies the runtime schema validation and inferred types used by the document model.
- **Native Fetch and timer APIs** — null repository path (external runtime interfaces): Provide the HTTP request and timeout mechanism used by the client.

##### Actors
- **SDK consumer** — null repository path (external caller): Application or developer code that invokes the published SDK API and receives parsed documents or operation results.
- **AEO declaration origin** — null repository path (external system): Host serving the document at the protocol’s well-known path.

#### Relationships

- **SDK consumer -> SDK public API**: Calls exported SDK functions; the package entry point re-exports the document and client APIs.
- **SDK public API -> Document model and operations**: Re-exports schemas, types, parsing, serialization, and claim-query functions.
- **SDK public API -> Well-known HTTP client**: Re-exports `fetchWellKnown` and `wellKnownUrl`.
- **SDK consumer -> Document model and operations**: Calls parsing, validation, serialization, or claim-query functions through the public API.
- **SDK consumer -> Well-known HTTP client**: Calls `fetchWellKnown` through the public API with an origin and optional fetch settings.
- **Well-known HTTP client -> AEO declaration origin**: Sends an HTTP GET to the constructed well-known URL; this is a direct fetch, not an asynchronous job dispatch.
- **Well-known HTTP client -> Native Fetch and timer APIs**: Uses `fetch` for the request and `setTimeout`/`clearTimeout` for the timeout.
- **Well-known HTTP client -> Document model and operations**: Passes successful response text to `parseDocument`; non-success responses throw instead.
- **Document model and operations -> Zod**: Uses schemas to validate document fields and construct typed parse results.
- **Document model and operations -> SDK consumer**: Returns parsed or safely validated results, serialized JSON, claim IDs, or a matching claim.

#### Coverage limits

The source excerpts establish the client-to-parser call and the schema/query behavior. They do not establish deployment details for declaration origins or consumer applications. The README documents Level 1 (Declare) conformance and defers signature verification and audit-endpoint posting; those capabilities are not part of the demonstrated workflow.

Main entry points: [`src/client.ts`](https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/client.ts) (Well-Known Client), [`src/document.ts`](https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/document.ts) (Document Operations), [`src/index.ts`](https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/index.ts) (Public SDK API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SDK Operations"]
  node_api["Public SDK API<br/>package entry point"]
  node_document["Document Operations<br/>schema and utilities"]
end

subgraph group_discovery["Well-Known Discovery"]
  node_client["Well-Known Client<br/>HTTP client"]
end

subgraph group_external["External Interfaces"]
  node_consumer(("SDK Consumer<br/>external caller"))
  node_origin(("AEO Declaration Origin<br/>external host"))
  node_zod["Zod<br/>validation dependency"]
  node_fetchapis["Fetch and Timer APIs<br/>runtime interfaces"]
end

node_consumer -->|"calls exports"| node_api
node_api -->|"re-exports"| node_document
node_api -->|"re-exports"| node_client
node_consumer -->|"uses operations"| node_document
node_consumer -->|"fetches origin"| node_client
node_client -->|"GET well-known URL"| node_origin
node_client -->|"uses request and timers"| node_fetchapis
node_client -->|"parses response"| node_document
node_document -->|"validates schemas"| node_zod
node_document -->|"returns results"| node_consumer

click node_api "https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/index.ts"
click node_document "https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/document.ts"
click node_client "https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/client.ts"

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_api,node_document toneBlue
class node_client toneAmber
class node_consumer,node_origin,node_zod,node_fetchapis toneMint
```

## Components

### SDK Operations

- [Public SDK API](https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/index.ts): package entry point · `src/index.ts`
- [Document Operations](https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/document.ts): schema and utilities · `src/document.ts`

### Well-Known Discovery

- [Well-Known Client](https://github.com/mizcausevic-dev/aeo-sdk-typescript/blob/main/src/client.ts): HTTP client · `src/client.ts`

### External Interfaces

- **SDK Consumer**: external caller
- **AEO Declaration Origin**: external host
- **Zod**: validation dependency
- **Fetch and Timer APIs**: runtime interfaces

## Connections

- SDK Consumer → Public SDK API: calls exports
- Public SDK API → Document Operations: re-exports
- Public SDK API → Well-Known Client: re-exports
- SDK Consumer → Document Operations: uses operations · Calls document operations through the public API.
- SDK Consumer → Well-Known Client: fetches origin · Calls fetchWellKnown through the public API.
- Well-Known Client → AEO Declaration Origin: GET well-known URL
- Well-Known Client → Fetch and Timer APIs: uses request and timers
- Well-Known Client → Document Operations: parses response · Successful response text is passed to parseDocument.
- Document Operations → Zod: validates schemas
- Document Operations → SDK Consumer: returns results · Returns parse or validation results, serialized JSON, claim IDs, or a matching claim.