# 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
```bash
# All services
ls services/

# Specific service
cd services/identity
```

### Find Package Code
```bash
# All packages
ls packages/

# Specific package
cd packages/database
```

### Find Documentation
```bash
# Architecture docs
ls docs/architecture/

# Deployment guides
ls docs/deployment/

# Service docs
find services -name README.md
```

### Find Infrastructure
```bash
# Terraform
ls infra/terraform/

# Kubernetes
ls infra/k8s/

# Scripts
ls infra/scripts/
```

## Development Workflow

1. **Local Development**
   ```bash
   pnpm install
   docker-compose up -d  # Start local services
   pnpm dev              # Start development servers
   ```

2. **Building**
   ```bash
   pnpm build            # Build all packages
   pnpm build --filter @the-order/{package}  # Build specific
   ```

3. **Testing**
   ```bash
   pnpm test             # Run all tests
   pnpm test --filter @the-order/{package}  # Test specific
   ```

4. **Deployment**
   ```bash
   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