the_order/PROJECT_STRUCTURE.md

The Order - Project Structure

Last Updated: 2025-01-27
Status: Comprehensive Structure Guide

Overview

This document provides a complete overview of The Order project structure, helping developers navigate the codebase efficiently.

Repository Layout

the-order/
├── apps/                          # Frontend applications
│   ├── mcp-legal/                # Legal management portal
│   ├── portal-public/            # Public-facing portal
│   └── portal-internal/          # Internal portal
│
├── services/                      # Backend microservices
│   ├── identity/                 # Identity & credential service
│   ├── intake/                   # Document intake service
│   ├── finance/                  # Payment & finance service
│   ├── dataroom/                 # Virtual data room service
│   ├── legal-documents/          # Legal document management
│   └── eresidency/               # e-Residency service
│
├── packages/                      # Shared libraries
│   ├── shared/                   # Common utilities
│   ├── database/                 # Database layer
│   ├── schemas/                  # Zod/JSON schemas
│   ├── auth/                     # Authentication
│   ├── storage/                  # Storage abstraction
│   ├── crypto/                   # Cryptography & KMS
│   ├── monitoring/               # Observability
│   ├── cache/                    # Caching utilities
│   └── [20+ more packages]
│
├── infra/                         # Infrastructure as Code
│   ├── terraform/                # Terraform configurations
│   │   ├── management-groups/   # Management group hierarchy
│   │   ├── policies/             # Azure policies
│   │   ├── modules/              # Reusable modules
│   │   │   └── regional-landing-zone/
│   │   └── multi-region/         # Multi-region deployment
│   ├── k8s/                      # Kubernetes manifests
│   │   ├── base/                 # Base configurations
│   │   └── overlays/             # Environment overlays
│   ├── monitoring/               # Monitoring configs
│   └── scripts/                   # Infrastructure scripts
│
├── docs/                          # Documentation
│   ├── architecture/             # Architecture documentation
│   ├── deployment/               # Deployment guides
│   │   └── azure/               # Azure-specific guides
│   ├── governance/               # Governance & policies
│   ├── integrations/             # Integration guides
│   │   └── entra-verifiedid/   # Entra VerifiedID
│   ├── legal/                    # Legal documentation
│   │   └── document-management/ # Document management
│   └── reports/                   # Project reports
│
├── scripts/                       # Utility scripts
│   ├── deploy/                   # Deployment scripts
│   ├── dev/                      # Development scripts
│   ├── backup/                   # Backup scripts
│   └── security/                 # Security scripts
│
├── assets/                         # Static assets
│   └── seals/                    # Credential seal images
│
└── manifests/                     # Application manifests

Key Directories

Applications (apps/)

Frontend applications built with React/Next.js:

• mcp-legal: Legal document management portal
• portal-public: Public-facing member portal
• portal-internal: Internal administrative portal

Services (services/)

Backend microservices (Node.js/TypeScript/Fastify):

• identity: eIDAS/DID, verifiable credentials, Entra VerifiedID
• intake: Document ingestion, OCR, classification
• finance: Payments, ledgers, invoicing
• dataroom: Virtual data rooms, deal management
• legal-documents: Comprehensive document management
• eresidency: e-Residency services

Packages (packages/)

Shared libraries used across services and apps:

• shared: Common utilities, middleware, error handling
• database: Database layer, migrations, queries
• schemas: Zod schemas for validation
• auth: Authentication and authorization
• storage: Storage abstraction (S3/GCS/Azure)
• crypto: Cryptography, KMS integration
• monitoring: Prometheus metrics, OpenTelemetry
• cache: Redis caching utilities

Infrastructure (infra/)

Infrastructure as Code:

• terraform/: Azure infrastructure
  • Management groups
  • Policies
  • Regional landing zones
  • Multi-region deployment
• k8s/: Kubernetes manifests
  • Base configurations
  • Environment overlays (dev/stage/prod)
• monitoring/: Prometheus, Grafana configs
• scripts/: Infrastructure automation

Documentation (docs/)

Comprehensive documentation:

• architecture/: System architecture, ADRs
• deployment/: Deployment guides
• governance/: Policies, security, compliance
• integrations/: Integration documentation
• legal/: Legal system documentation
• reports/: Project status, reviews

Navigation Guide

For New Developers

1. Start with README.md (project root)
2. Review PROJECT_STRUCTURE.md (this file)
3. Check docs/architecture/README.md
4. Read service-specific READMEs in services/*/README.md

For Infrastructure Engineers

1. infra/README.md - Infrastructure overview
2. infra/terraform/README.md - Terraform guide
3. infra/k8s/README.md - Kubernetes guide
4. docs/deployment/azure/ - Azure deployment guides

For Backend Developers

1. services/*/README.md - Service documentation
2. packages/*/README.md - Package documentation
3. docs/architecture/ - Architecture decisions
4. docs/integrations/ - Integration guides

For Frontend Developers

1. apps/*/README.md - Application documentation
2. packages/ui/README.md - UI component library
3. docs/architecture/ - Frontend architecture

File Naming Conventions

Documentation

• README.md - Directory overview
• ARCHITECTURE.md - Architecture documentation
• DEPLOYMENT.md - Deployment guides
• GUIDE.md - How-to guides
• SUMMARY.md - Executive summaries

Code

• index.ts - Main entry point
• *.service.ts - Service layer
• *.route.ts - API routes
• *.test.ts - Test files
• *.config.ts - Configuration files

Infrastructure

• main.tf - Main Terraform file
• variables.tf - Variables
• outputs.tf - Outputs
• versions.tf - Version constraints
• deployment.yaml - Kubernetes deployment
• service.yaml - Kubernetes service

Common Patterns

Service Structure

services/{service-name}/
├── src/
│   ├── index.ts              # Entry point
│   ├── routes/               # API routes
│   ├── services/             # Business logic
│   └── types/                # TypeScript types
├── tests/                    # Test files
├── k8s/                      # Kubernetes manifests
├── Dockerfile                # Container definition
├── package.json              # Dependencies
└── README.md                 # Service documentation

Package Structure

packages/{package-name}/
├── src/
│   ├── index.ts              # Main exports
│   └── [module files]
├── tests/                    # Test files
├── package.json              # Package definition
└── README.md                 # Package documentation

Infrastructure Structure

infra/{tool}/
├── [config files]
├── modules/                   # Reusable modules
└── README.md                  # Infrastructure guide

Quick Reference

Find Service Code

# All services
ls services/

# Specific service
cd services/identity

Find Package Code

# All packages
ls packages/

# Specific package
cd packages/database

Find Documentation

# Architecture docs
ls docs/architecture/

# Deployment guides
ls docs/deployment/

# Service docs
find services -name README.md

Find Infrastructure

# Terraform
ls infra/terraform/

# Kubernetes
ls infra/k8s/

# Scripts
ls infra/scripts/

Development Workflow

1. Local Development

   pnpm install
   docker-compose up -d  # Start local services
   pnpm dev              # Start development servers
   

2. Building

   pnpm build            # Build all packages
   pnpm build --filter @the-order/{package}  # Build specific
   

3. Testing

   pnpm test             # Run all tests
   pnpm test --filter @the-order/{package}  # Test specific
   

4. Deployment

   source infra/scripts/azure-load-env.sh
   ./infra/scripts/azure-deploy.sh
   

Important Files

• package.json - Root package configuration
• pnpm-workspace.yaml - Monorepo workspace config
• tsconfig.json - TypeScript configuration
• turbo.json - Turborepo configuration
• .env - Environment variables (not in git)
• docker-compose.yml - Local development stack

Getting Help

• Architecture Questions: See docs/architecture/
• Deployment Issues: See docs/deployment/
• Service Documentation: See services/*/README.md
• Package Documentation: See packages/*/README.md

---

Last Updated: 2025-01-27