# wewb/nomad architecture

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

- Interactive diagram: https://gitdiagram.com/wewb/nomad
- Repository: https://github.com/wewb/nomad

## Overview

##### Main Components

- Frontend (track-platform):
- A React-based application (notice the files under track-platform/src) using Vite for rapid development.
- Contains pages such as Login, Dashboard, ApplicationDetail, Documentation, and various tracking-related views.
- Responsible for rendering the user interface and interacting with the backend via API calls.

- Backend (track-server):
- Implements API routes, handles authentication, and manages business logic.
- The src/routes, src/models, src/middleware, and src/services directories indicate a Node.js/Express-style architecture.
- Responsible for receiving tracking events and handling data persistence (even if the database is abstracted via models).

- SDK (track-sdk):
- Provides the core tracking logic that can be integrated into websites or other clients.
- Contains the main tracking functions (track-point.ts) and type definitions to ensure type safety.
- Likely used both by the frontend and potentially by external systems wanting to use the tracking capabilities.

- Documentation and Requirements:
- The doc directory (and requirement docs) provides requirements/specifications which outline the intended behavior and possible integration concerns.

##### Relationships and Interactions

- The Backend interacts with storage or data persistence via its models (e.g., Application, Event, User) and employs middleware for authentication, validation, etc.
- The SDK (track-sdk) is the core library that encapsulates tracking logic. It can be visualized as an independent module that the Frontend (and possibly other clients) integrates with to report events or errors.
- Additionally, the data flow might include error reports, tracking events, and user activity logs that start at the frontend/SDK, travel to the backend, and are stored/processed.

##### Key Architectural Patterns and Design Principles

- Separation of Concerns: The frontend, backend, and SDK are clearly separated—each package serves a different responsibility.
- Modular Design: The SDK is built as an independent package, which highlights extensibility and reusability.
- API-driven Interaction: The frontend relies on REST API endpoints provided by the backend.
- Type Safety and Modern Tooling: With TypeScript files (.ts, .tsx) and configurations like tsconfig.json and vite.config.ts, modern tooling is employed to maintain code quality and consistency.

##### Technologies and Frameworks

- Frontend: React, TypeScript, Vite, and Less for styling.
- Backend: Node.js with an Express-like structure (using middleware, routes, and models), TypeScript.
- SDK: TypeScript-based library providing public APIs for tracking.
- Additional tools: HTTP server for SDK development, npm for package management (noted with package-lock.json files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend (track-platform)"
        F0["Frontend (track-platform)"]:::frontend
        FP_Pages["Pages: Login,Dashboard,ApplicationDetail,Documentation"]:::frontend
        FP_Components["UI Components: Layout,ErrorBoundary,PrivateRoute"]:::frontend
        FP_Config["Config: vite.config.ts,tsconfig.json"]:::frontend
        F0 --> FP_Pages
        F0 --> FP_Components
        F0 --> FP_Config
    end

    %% Backend Subgraph
    subgraph "Backend (track-server)"
        B0["Backend (track-server)"]:::backend
        BS_Routes["Routes: API Endpoints"]:::backend
        BS_Middleware["Middleware: Auth/Validation"]:::backend
        BS_Services["Services: Business Logic"]:::backend
        BS_Models["Models: Data Persistence"]:::backend
        B0 --> BS_Routes
        B0 --> BS_Middleware
        B0 --> BS_Services
        B0 --> BS_Models
        BS_Routes -->|"uses"| BS_Middleware
        BS_Middleware -->|"routes"| BS_Services
        BS_Services -->|"stores_in"| BS_Models
    end

    %% SDK Subgraph
    subgraph "SDK (track-sdk)"
        S0["SDK (track-sdk)"]:::sdk
        SDK_Core["Core Tracking Logic (track-point.ts,Type Definitions)"]:::sdk
        S0 --> SDK_Core
    end

    %% Documentation Node
    DOC["Documentation (Requirement Docs)"]:::doc

    %% Data Flow Connections
    FP_Pages -->|"HTTP_API_Calls"| BS_Routes
    FP_Pages -->|"Event_Tracking"| SDK_Core

    %% Documentation References
    DOC -->|"docs_for"| F0
    DOC -->|"docs_for"| B0
    DOC -->|"docs_for"| S0

    %% Click Events for Component Mapping
    click F0 "https://github.com/wewb/nomad/tree/main/track-platform"
    click B0 "https://github.com/wewb/nomad/tree/main/track-server"
    click S0 "https://github.com/wewb/nomad/tree/main/track-sdk"
    click DOC "https://github.com/wewb/nomad/tree/main/doc"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef sdk fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef doc fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
