Skip to content

Repository Directory Map

This document provides a high-level map of the v4-monorepo directory structure to help you navigate the codebase.

Root Directory

  • Root Files
  • README.md - Overview of the entire repository
  • CONTRIBUTING.md - Guide for new contributors
  • CLAUDE.md - Development guidelines and standards
  • package.json - Main package configuration
  • nx.json - NX workspace configuration
  • tsconfig.base.json - Base TypeScript configuration

Core Directories

Applications (/apps)

Contains standalone services and applications:

  • datastream/ - Real-time market data service
  • funding/ - Funding rate calculation service
  • instruments/ - Option instrument definitions service
  • orderbook/ - Order management and matching engine
  • poseidon/ - Risk analysis service
  • relayer/ - Web3 transaction execution service
  • sequencer/ - User positions and risk management
  • websockets/ - Real-time event streaming service
  • optionMakerAgent/ - Options market making bot
  • perpMakerAgent/ - Perpetuals market making bot

Libraries (/libs)

Shared code libraries used across multiple applications:

  • chainpyon/ - Web3 Python utilities
  • commons/ - Shared Python utilities
  • commons-ts/ - Shared TypeScript utilities
  • connections-ts/ - Database and service connection libraries
  • mockData/ - Test data generation
  • tools/ - Build and development tools

Scripts (/scripts)

Utility scripts for development, testing, and CI/CD:

  • build/ - Build-related scripts
  • dependencies/ - Dependency management scripts
  • docker/ - Docker-related utilities
  • docker-compose/ - Docker Compose scripts
  • github-actions/ - GitHub Actions utilities
  • lib/ - Shared script utilities
  • publish/ - Package publishing scripts
  • python/ - Python-specific scripts
  • testing/ - Test setup and execution scripts
  • typescript/ - TypeScript-specific scripts
  • utilities/ - General utility scripts

Documentation (/documentation)

Documentation resources:

  • adr/ - Architectural Decision Records
  • branch-mgmt/ - Git branch management guides
  • diagrams/ - System and component diagrams
  • examples/ - Example code and configuration
  • templates/ - Template files for standardized documents
  • bqSchema/ - BigQuery schema definitions
  • visual-documentation.md - Comprehensive visual system documentation

Infrastructure (/terraform)

Infrastructure as Code (IaC) definitions:

  • infra/ - Core infrastructure configuration
  • support_infrastructure/ - Support service configuration

Key Application Structure

Each application generally follows this structure:

app-name/
├── src/              # Source code
│   ├── utils/        # Utility functions
│   ├── types/        # TypeScript types
│   ├── middleware/   # Middleware components
│   ├── validators/   # Input validation
│   ├── app.ts        # Main application entry
│   └── index.ts      # Package exports
├── tests/            # Tests
│   ├── unit/         # Unit tests
│   └── it/           # Integration tests
├── README.md         # Project documentation
├── package.json      # Package configuration
├── project.json      # NX project configuration
└── tsconfig.json     # TypeScript configuration

Key Library Structure

Libraries typically follow this structure:

lib-name/
├── src/              # Source code
│   ├── constants/    # Constants and configuration
│   ├── types/        # TypeScript types
│   ├── utils/        # Utility functions
│   ├── validators/   # Validation logic
│   └── index.ts      # Package exports
├── tests/            # Tests
│   ├── unit/         # Unit tests
│   └── integration/  # Integration tests
├── README.md         # Library documentation
├── package.json      # Package configuration
└── project.json      # NX project configuration
  • Use nx show projects to list all projects in the monorepo
  • Use nx graph to visualize project dependencies
  • Search for specific functionality with nx-affected commands
  • Explore the documentation/ directory for detailed architecture diagrams

Core Development Paths

  • Backend Service Development: Focus on the apps/ directory
  • Shared Utilities: Explore the libs/ directory
  • Infrastructure: Look at the terraform/ directory
  • Build/CI Configuration: Check the scripts/ directory

Additional Resources