wifi-densepose/npm/packages/agentic-synth/docs/DIRECTORY_STRUCTURE.md

Directory Structure

Complete directory structure for agentic-synth package.

packages/agentic-synth/
├── src/
│   ├── index.ts                    # Main SDK entry point
│   ├── types/
│   │   └── index.ts                # Core type definitions
│   │
│   ├── sdk/
│   │   ├── AgenticSynth.ts         # Main SDK class
│   │   └── index.ts                # SDK exports
│   │
│   ├── core/
│   │   ├── Config.ts               # Configuration management
│   │   ├── Cache.ts                # Cache manager (LRU, no Redis)
│   │   ├── Logger.ts               # Logging system
│   │   └── index.ts
│   │
│   ├── generators/
│   │   ├── base.ts                 # Base generator interface
│   │   ├── Hub.ts                  # Generator registry
│   │   ├── TimeSeries.ts           # Time-series generator
│   │   ├── Events.ts               # Event generator
│   │   ├── Structured.ts           # Structured data generator
│   │   └── index.ts
│   │
│   ├── models/
│   │   ├── base.ts                 # Model provider interface
│   │   ├── Router.ts               # Model routing logic
│   │   ├── providers/
│   │   │   ├── Gemini.ts          # Gemini API provider
│   │   │   ├── OpenRouter.ts      # OpenRouter API provider
│   │   │   └── index.ts
│   │   └── index.ts
│   │
│   ├── integrations/
│   │   ├── Manager.ts              # Integration manager
│   │   ├── base.ts                 # Integration adapter interface
│   │   ├── Midstreamer.ts          # Midstreamer adapter
│   │   ├── AgenticRobotics.ts      # Agentic-Robotics adapter
│   │   ├── Ruvector.ts             # Ruvector adapter
│   │   └── index.ts
│   │
│   ├── bin/
│   │   ├── cli.ts                  # CLI entry point
│   │   ├── commands/
│   │   │   ├── generate.ts        # Generate command
│   │   │   ├── batch.ts           # Batch command
│   │   │   ├── cache.ts           # Cache management
│   │   │   ├── config.ts          # Config management
│   │   │   └── index.ts
│   │   └── index.ts
│   │
│   └── utils/
│       ├── validation.ts           # Validation helpers
│       ├── serialization.ts        # Serialization helpers
│       ├── prompts.ts              # AI prompt templates
│       └── index.ts
│
├── tests/
│   ├── unit/
│   │   ├── generators/
│   │   │   ├── TimeSeries.test.ts
│   │   │   ├── Events.test.ts
│   │   │   └── Structured.test.ts
│   │   ├── models/
│   │   │   └── Router.test.ts
│   │   ├── core/
│   │   │   ├── Cache.test.ts
│   │   │   └── Config.test.ts
│   │   └── sdk/
│   │       └── AgenticSynth.test.ts
│   │
│   ├── integration/
│   │   ├── e2e.test.ts
│   │   ├── midstreamer.test.ts
│   │   ├── robotics.test.ts
│   │   └── ruvector.test.ts
│   │
│   └── fixtures/
│       ├── schemas/
│       │   ├── timeseries.json
│       │   ├── events.json
│       │   └── structured.json
│       └── configs/
│           └── test-config.json
│
├── examples/
│   ├── basic/
│   │   ├── timeseries.ts
│   │   ├── events.ts
│   │   └── structured.ts
│   │
│   ├── integrations/
│   │   ├── midstreamer-pipeline.ts
│   │   ├── robotics-workflow.ts
│   │   ├── ruvector-search.ts
│   │   └── full-integration.ts
│   │
│   ├── advanced/
│   │   ├── custom-generator.ts
│   │   ├── model-routing.ts
│   │   └── batch-generation.ts
│   │
│   └── cli/
│       ├── basic-usage.sh
│       ├── batch-config.yaml
│       └── advanced-usage.sh
│
├── docs/
│   ├── ARCHITECTURE.md             # Architecture documentation
│   ├── API.md                      # API reference
│   ├── INTEGRATION.md              # Integration guide
│   ├── DIRECTORY_STRUCTURE.md      # This file
│   └── DEVELOPMENT.md              # Development guide
│
├── config/
│   ├── .agentic-synth.example.json # Example config file
│   └── schemas/
│       ├── config.schema.json     # Config JSON schema
│       └── generation.schema.json # Generation options schema
│
├── bin/
│   └── cli.js                      # Compiled CLI entry (after build)
│
├── dist/                           # Compiled output (generated)
│   ├── index.js
│   ├── index.d.ts
│   └── ...
│
├── package.json
├── tsconfig.json
├── .eslintrc.json
├── .prettierrc
├── .gitignore
├── README.md
├── LICENSE
└── CHANGELOG.md

Key Directories

/src

Source code directory containing all TypeScript files.

Subdirectories:

• sdk/ - Main SDK implementation
• core/ - Core utilities (config, cache, logger)
• generators/ - Data generation logic
• models/ - AI model integrations
• integrations/ - External tool adapters
• bin/ - CLI implementation
• utils/ - Helper functions
• types/ - TypeScript type definitions

/tests

Test files using Vitest framework.

Subdirectories:

• unit/ - Unit tests for individual modules
• integration/ - Integration tests with external services
• fixtures/ - Test data and configurations

/examples

Example code demonstrating usage patterns.

Subdirectories:

• basic/ - Simple usage examples
• integrations/ - Integration examples
• advanced/ - Advanced patterns
• cli/ - CLI usage examples

/docs

Documentation files.

Files:

• ARCHITECTURE.md - System architecture and ADRs
• API.md - Complete API reference
• INTEGRATION.md - Integration guide
• DEVELOPMENT.md - Development guide

/config

Configuration files and schemas.

/dist

Compiled JavaScript output (generated by TypeScript compiler).

Module Organization

Core Module (src/core/)

Provides foundational functionality:

• Configuration loading and management
• Caching without Redis
• Logging system
• Error handling

Generator Module (src/generators/)

Implements data generation:

• Base generator interface
• Generator registry (Hub)
• Built-in generators (TimeSeries, Events, Structured)
• Custom generator support

Model Module (src/models/)

AI model integration:

• Provider interface
• Model router with fallback
• Gemini integration
• OpenRouter integration
• Cost calculation

Integration Module (src/integrations/)

Optional external integrations:

• Integration manager
• Midstreamer adapter
• Agentic-Robotics adapter
• Ruvector adapter
• Custom integration support

SDK Module (src/sdk/)

Public SDK interface:

• AgenticSynth main class
• High-level API methods
• Integration coordination

CLI Module (src/bin/)

Command-line interface:

• CLI entry point
• Command implementations
• Argument parsing
• Output formatting

Utils Module (src/utils/)

Utility functions:

• Validation helpers
• Serialization (JSON, CSV, Parquet)
• Prompt templates
• Common helpers

File Naming Conventions

• PascalCase: Classes and main modules (AgenticSynth.ts, ModelRouter.ts)
• camelCase: Utility files (validation.ts, prompts.ts)
• lowercase: Base interfaces and types (base.ts, index.ts)
• kebab-case: Config files (.agentic-synth.json)

Import/Export Pattern

Each directory has an index.ts that exports public APIs:

// src/generators/index.ts
export { Generator, BaseGenerator } from './base.js';
export { GeneratorHub } from './Hub.js';
export { TimeSeriesGenerator } from './TimeSeries.js';
export { EventGenerator } from './Events.js';
export { StructuredGenerator } from './Structured.js';

Build Output Structure

After npm run build, the dist/ directory mirrors src/:

dist/
├── index.js
├── index.d.ts
├── sdk/
│   ├── AgenticSynth.js
│   └── AgenticSynth.d.ts
├── generators/
│   ├── base.js
│   ├── base.d.ts
│   └── ...
└── ...

Package Exports

package.json defines multiple entry points:

{
  "exports": {
    ".": "./dist/index.js",
    "./sdk": "./dist/sdk/index.js",
    "./generators": "./dist/generators/index.js",
    "./integrations": "./dist/integrations/index.js"
  }
}

Development Workflow

1. Source files in src/ (TypeScript)
2. Build with tsc → outputs to dist/
3. Test with vitest → runs from tests/
4. Examples in examples/ → use built SDK
5. Documentation in docs/ → reference for users

Future Additions

Planned additions to directory structure:

• src/plugins/ - Plugin system for custom generators
• src/middleware/ - Middleware for request/response processing
• benchmarks/ - Performance benchmarks
• scripts/ - Build and deployment scripts
• .github/ - GitHub Actions workflows

---

This structure provides:

• ✅ Clear separation of concerns
• ✅ Modular architecture
• ✅ Easy to navigate and maintain
• ✅ Scalable for future additions
• ✅ Standard TypeScript/Node.js patterns