# node-ntrip/caster architecture

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

- Interactive diagram: https://gitdiagram.com/node-ntrip/caster
- Repository: https://github.com/node-ntrip/caster

## Overview

1. This repository is a TypeScript library, not a full app. Its main job is to implement an NTRIP caster that can also act as an NTRIP client/server bridge and speak multiple transport protocols around RTCM/NMEA data.

2. The center of the design is the `Caster` domain layer (`src/caster.ts`) with supporting models like `Connection`, `Mountpoint`, `Sourcetable`, and `Auth`. These pieces represent the runtime registry of streams, connected clients/sources, and access control decisions.

3. `src/auth.ts` defines the authentication boundary. The README shows authentication is user-supplied through an `authManager.authenticate(...)` callback, so auth is intentionally pluggable rather than hardcoded.

4. Transport handling is abstracted under `src/transport/`. This is the main architectural boundary between the caster core and the outside world: transports adapt external I/O into a common internal flow of connections and stream data.

5. The server-side NTRIP entry point is `src/transport/server/ntrip.ts`, backed by `src/transport/server/socket.ts`. This layer listens on a port, handles TLS if configured, and negotiates HTTP/RTSP/RTP plus NTRIP V1/V2 behavior.

6. The push/pull bridge lives in `src/transport/client/ntrip-push-pull.ts`. It connects this caster to another caster in either `push` or `pull` mode, mapping a local mountpoint to a remote mountpoint and handling remote credentials and protocol selection.

7. Additional client/server transports extend the same model for non-NTRIP I/O:
   - `serial.ts` for serial port input/output
   - `socket-client.ts` for raw TCP/IP client connections
   - `file.ts` and `stream.ts` for file and stream-based reading/writing
   These are alternative ingress/egress paths into the same caster/core stream pipeline.

8. Utility code in `src/util/` supports protocol and metadata handling:
   - `ntrip-http-parser.ts` parses NTRIP-style HTTP requests
   - `rtp.ts` handles RTP-related framing/processing
   - `auto-source-entry.ts` likely builds sourcetable/source metadata automatically
   - `simple-logger.ts` provides lightweight internal logging

9. `src/sourcetable.ts` is the metadata publication layer. In NTRIP, sourcetables describe available mountpoints and streams, so this module is the outward-facing catalog generated from the caster’s internal state and transport configuration.

10. `src/index.ts` is the public API surface that re-exports the library’s main entry points. For an architecture diagram, this is the boundary consumers use to create a `Caster` and attach one or more transports.

11. The repository includes a local type declaration under `src/@types/ecef-projector`, which suggests some geometry/coordinate-projection functionality is used indirectly for source metadata or related calculations, even though it is not a primary subsystem.

12. Tests are narrowly scoped around protocol parsing, with `src/__tests__/util/ntrip-http-parser.ts` covering the HTTP/NTRIP parser. That indicates the most critical logic is in request interpretation and transport negotiation rather than in business workflows.

13. A useful way to diagram the runtime flow is:
   external client/source → transport adapter → auth gate → connection/mountpoint handling in the caster → sourcetable/stream distribution → other clients or downstream transports.
   The push/pull bridge is the main feedback loop, because it can act as both sink and source between two casters.

14. In short, the architecture is a protocol/transport adapter layer around a central caster core, with pluggable authentication and multiple I/O backends feeding a shared mountpoint/sourcetable model.

Main entry points: [`src/caster.ts`](https://github.com/node-ntrip/caster/blob/master/src/caster.ts) (Caster), [`src/transport/index.ts`](https://github.com/node-ntrip/caster/blob/master/src/transport/index.ts) (Transport API), [`src/transport/server/ntrip.ts`](https://github.com/node-ntrip/caster/blob/master/src/transport/server/ntrip.ts) (NTRIP Server), [`src/sourcetable.ts`](https://github.com/node-ntrip/caster/blob/master/src/sourcetable.ts) (Sourcetable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_src_index["Index<br/>public api<br/>[index.ts]"]
end

subgraph group_core["Caster core"]
  node_src_caster["Caster<br/>domain core<br/>[caster.ts]"]
  node_src_auth["Auth<br/>[auth.ts]"]
  node_src_connection["Connection<br/>runtime model<br/>[connection.ts]"]
  node_src_mountpoint["Mountpoint<br/>stream model<br/>[mountpoint.ts]"]
  node_src_sourcetable["Sourcetable<br/>catalog model<br/>[sourcetable.ts]"]
end

subgraph group_transport["Transports"]
  node_src_transport_index["Transport API<br/>transport facade<br/>[index.ts]"]
  node_src_transport_transport["Transport<br/>adapter contract<br/>[transport.ts]"]
  node_src_transport_server_ntrip["NTRIP Server<br/>server transport<br/>[ntrip.ts]"]
  node_src_transport_server_socket["Socket Server<br/>socket I/O<br/>[socket.ts]"]
  node_src_transport_client_bridge["Push/Pull<br/>bridge transport<br/>[ntrip-push-pull.ts]"]
  node_src_transport_client_serial["Serial<br/>client transport<br/>[serial.ts]"]
  node_src_transport_client_socket["Socket Client<br/>client transport<br/>[socket-client.ts]"]
  node_src_transport_misc_file["File<br/>misc transport<br/>[file.ts]"]
  node_src_transport_misc_stream["Stream<br/>misc transport<br/>[stream.ts]"]
end

subgraph group_util["Utilities"]
  node_src_util_http["HTTP Parser"]
  node_src_util_rtp["RTP<br/>framing util<br/>[rtp.ts]"]
  node_src_util_auto_source["Auto Source<br/>metadata util"]
  node_src_util_logger["Logger<br/>logging util<br/>[simple-logger.ts]"]
  node_src_types_ecef["ECEF Types<br/>ambient types<br/>[index.d.ts]"]
end

node_src_index -->|"exports"| node_src_caster
node_src_index -->|"exports"| node_src_transport_index
node_src_caster -->|"uses"| node_src_auth
node_src_caster -->|"tracks"| node_src_connection
node_src_caster -->|"routes"| node_src_mountpoint
node_src_caster -->|"publishes"| node_src_sourcetable
node_src_transport_index -->|"defines"| node_src_transport_transport
node_src_transport_index -->|"includes"| node_src_transport_server_ntrip
node_src_transport_index -->|"includes"| node_src_transport_client_bridge
node_src_transport_index -->|"includes"| node_src_transport_client_serial
node_src_transport_index -->|"includes"| node_src_transport_client_socket
node_src_transport_index -->|"includes"| node_src_transport_misc_file
node_src_transport_index -->|"includes"| node_src_transport_misc_stream
node_src_transport_server_ntrip -->|"uses"| node_src_transport_server_socket
node_src_transport_server_ntrip -->|"parses"| node_src_util_http
node_src_transport_server_ntrip -->|"frames"| node_src_util_rtp
node_src_transport_client_bridge -->|"negotiates"| node_src_util_http
node_src_transport_client_bridge -->|"bridges"| node_src_caster
node_src_transport_client_serial -->|"feeds"| node_src_caster
node_src_transport_client_socket -->|"feeds"| node_src_caster
node_src_transport_misc_file -->|"feeds"| node_src_caster
node_src_transport_misc_stream -->|"feeds"| node_src_caster
node_src_sourcetable -->|"describes"| node_src_mountpoint
node_src_sourcetable -->|"generates"| node_src_util_auto_source
node_src_util_auto_source -->|"types"| node_src_types_ecef
node_src_transport_server_ntrip -->|"logs"| node_src_util_logger
node_src_caster -->|"logs"| node_src_util_logger

click node_src_index "https://github.com/node-ntrip/caster/blob/master/src/index.ts"
click node_src_caster "https://github.com/node-ntrip/caster/blob/master/src/caster.ts"
click node_src_auth "https://github.com/node-ntrip/caster/blob/master/src/auth.ts"
click node_src_connection "https://github.com/node-ntrip/caster/blob/master/src/connection.ts"
click node_src_mountpoint "https://github.com/node-ntrip/caster/blob/master/src/mountpoint.ts"
click node_src_sourcetable "https://github.com/node-ntrip/caster/blob/master/src/sourcetable.ts"
click node_src_transport_index "https://github.com/node-ntrip/caster/blob/master/src/transport/index.ts"
click node_src_transport_transport "https://github.com/node-ntrip/caster/blob/master/src/transport/transport.ts"
click node_src_transport_server_ntrip "https://github.com/node-ntrip/caster/blob/master/src/transport/server/ntrip.ts"
click node_src_transport_server_socket "https://github.com/node-ntrip/caster/blob/master/src/transport/server/socket.ts"
click node_src_transport_client_bridge "https://github.com/node-ntrip/caster/blob/master/src/transport/client/ntrip-push-pull.ts"
click node_src_transport_client_serial "https://github.com/node-ntrip/caster/blob/master/src/transport/client/serial.ts"
click node_src_transport_client_socket "https://github.com/node-ntrip/caster/blob/master/src/transport/client/socket-client.ts"
click node_src_transport_misc_file "https://github.com/node-ntrip/caster/blob/master/src/transport/misc/file.ts"
click node_src_transport_misc_stream "https://github.com/node-ntrip/caster/blob/master/src/transport/misc/stream.ts"
click node_src_util_http "https://github.com/node-ntrip/caster/blob/master/src/util/ntrip-http-parser.ts"
click node_src_util_rtp "https://github.com/node-ntrip/caster/blob/master/src/util/rtp.ts"
click node_src_util_auto_source "https://github.com/node-ntrip/caster/blob/master/src/util/auto-source-entry.ts"
click node_src_util_logger "https://github.com/node-ntrip/caster/blob/master/src/util/simple-logger.ts"
click node_src_types_ecef "https://github.com/node-ntrip/caster/blob/master/src/@types/ecef-projector/index.d.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_src_index toneBlue
class node_src_caster,node_src_auth,node_src_connection,node_src_mountpoint,node_src_sourcetable toneAmber
class node_src_transport_index,node_src_transport_transport,node_src_transport_server_ntrip,node_src_transport_server_socket,node_src_transport_client_bridge,node_src_transport_client_serial,node_src_transport_client_socket,node_src_transport_misc_file,node_src_transport_misc_stream toneMint
class node_src_util_http,node_src_util_rtp,node_src_util_auto_source,node_src_util_logger,node_src_types_ecef toneRose
```

## Components

### Public API

Library entry points used by consumers

- [Index](https://github.com/node-ntrip/caster/blob/master/src/index.ts): public api · Re-exports the library surface for consumers · `src/index.ts`

### Caster core

Runtime registry, access control, and metadata model

- [Caster](https://github.com/node-ntrip/caster/blob/master/src/caster.ts): domain core · Central runtime that manages mountpoints, connections, and stream flow · `src/caster.ts`
- [Auth](https://github.com/node-ntrip/caster/blob/master/src/auth.ts): auth boundary · Pluggable authentication and authorization decisions · `src/auth.ts`
- [Connection](https://github.com/node-ntrip/caster/blob/master/src/connection.ts): runtime model · Represents a connected source or client · `src/connection.ts`
- [Mountpoint](https://github.com/node-ntrip/caster/blob/master/src/mountpoint.ts): stream model · Named stream endpoint managed by the caster · `src/mountpoint.ts`
- [Sourcetable](https://github.com/node-ntrip/caster/blob/master/src/sourcetable.ts): catalog model · Publishes available mountpoints and stream metadata · `src/sourcetable.ts`

### Transports

Adapters that connect external I/O to the caster

- [Transport API](https://github.com/node-ntrip/caster/blob/master/src/transport/index.ts): transport facade · Shared transport abstractions and wiring · `src/transport/index.ts`
- [Transport](https://github.com/node-ntrip/caster/blob/master/src/transport/transport.ts): adapter contract · Base transport interface and common transport behavior · `src/transport/transport.ts`
- [NTRIP Server](https://github.com/node-ntrip/caster/blob/master/src/transport/server/ntrip.ts): server transport · Listens for NTRIP clients and negotiates protocol variants · `src/transport/server/ntrip.ts`
- [Socket Server](https://github.com/node-ntrip/caster/blob/master/src/transport/server/socket.ts): socket I/O · Socket and TLS support for server-side transports · `src/transport/server/socket.ts`
- [Push/Pull](https://github.com/node-ntrip/caster/blob/master/src/transport/client/ntrip-push-pull.ts): bridge transport · Connects this caster to another caster as push or pull · `src/transport/client/ntrip-push-pull.ts`
- [Serial](https://github.com/node-ntrip/caster/blob/master/src/transport/client/serial.ts): client transport · Serial port ingress and egress · `src/transport/client/serial.ts`
- [Socket Client](https://github.com/node-ntrip/caster/blob/master/src/transport/client/socket-client.ts): client transport · Raw TCP/IP client connections · `src/transport/client/socket-client.ts`
- [File](https://github.com/node-ntrip/caster/blob/master/src/transport/misc/file.ts): misc transport · File-based reading and writing · `src/transport/misc/file.ts`
- [Stream](https://github.com/node-ntrip/caster/blob/master/src/transport/misc/stream.ts): misc transport · Generic stream-based reading and writing · `src/transport/misc/stream.ts`

### Utilities

Protocol parsing, framing, and support helpers

- [HTTP Parser](https://github.com/node-ntrip/caster/blob/master/src/util/ntrip-http-parser.ts): parser · Parses NTRIP-style HTTP requests · `src/util/ntrip-http-parser.ts`
- [RTP](https://github.com/node-ntrip/caster/blob/master/src/util/rtp.ts): framing util · Handles RTP-related framing and processing · `src/util/rtp.ts`
- [Auto Source](https://github.com/node-ntrip/caster/blob/master/src/util/auto-source-entry.ts): metadata util · Builds sourcetable source entries automatically · `src/util/auto-source-entry.ts`
- [Logger](https://github.com/node-ntrip/caster/blob/master/src/util/simple-logger.ts): logging util · Lightweight internal logging helper · `src/util/simple-logger.ts`
- [ECEF Types](https://github.com/node-ntrip/caster/blob/master/src/@types/ecef-projector/index.d.ts): ambient types · Local type declarations for coordinate/projection support · `src/@types/ecef-projector/index.d.ts`

## Connections

- Index → Caster: exports · Public API exposes the central caster
- Index → Transport API: exports · Public API exposes transport entry points
- Caster → Auth: uses · Caster delegates access decisions to pluggable auth
- Caster → Connection: tracks · Caster maintains active source/client connections
- Caster → Mountpoint: routes · Caster binds traffic to named mountpoints
- Caster → Sourcetable: publishes · Caster state feeds sourcetable generation
- Transport API → Transport: defines · Transport layer exposes the shared adapter contract
- Transport API → NTRIP Server: includes · Server-side NTRIP transport is a main adapter
- Transport API → Push/Pull: includes · Push/pull bridge is a main adapter
- Transport API → Serial: includes · Serial transport is a supported adapter
- Transport API → Socket Client: includes · Raw socket client transport is supported
- Transport API → File: includes · File transport participates in the shared model
- Transport API → Stream: includes · Stream transport participates in the shared model
- NTRIP Server → Socket Server: uses · NTRIP server relies on socket/TLS handling
- NTRIP Server → HTTP Parser: parses · Server negotiates requests through the NTRIP HTTP parser
- NTRIP Server → RTP: frames · Server handles RTP-related data handling
- Push/Pull → HTTP Parser: negotiates · Bridge mode selects and interprets remote protocol behavior
- Push/Pull → Caster: bridges · Bridge connects local mountpoints to remote caster flow
- Serial → Caster: feeds · Serial I/O feeds the caster stream pipeline
- Socket Client → Caster: feeds · Socket client I/O feeds the caster stream pipeline
- File → Caster: feeds · File I/O is adapted into the caster pipeline
- Stream → Caster: feeds · Stream I/O is adapted into the caster pipeline
- Sourcetable → Mountpoint: describes · Sourcetable catalogs mountpoints and stream metadata
- Sourcetable → Auto Source: generates · Auto source entry utility helps build metadata
- Auto Source → ECEF Types: types · Metadata generation may depend on ambient coordinate types
- NTRIP Server → Logger: logs · Server transport uses internal logging
- Caster → Logger: logs · Core runtime emits operational logs
