docs(infrastructure): 📝 Update migration completeness and deployment practices documentation to standardize infrastructure, deployment, and feature structures
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
This commit is contained in:
Quinn Ftw
parent
f9ac610ac1
commit
529d2c450c
8 changed files with 47 additions and 45 deletions
|
|
@ -17,7 +17,7 @@ The deployment pattern implements Feature-Sliced Design (FSD) compliance by sepa
|
|||
| Layer | Location | Responsibility |
|
||||
|-------|----------|----------------|
|
||||
| **Core Application** | `codebase/features/marketplace/frontend-public/` | Pure, deployment-agnostic React application |
|
||||
| **Deployment Packages** | `codebase/@deployments/{brand}.www/` | Brand-specific configuration, themes, and verticals |
|
||||
| **Deployment Packages** | `deployments/@domains/{brand}.www/root/` | Brand-specific configuration, themes, and verticals |
|
||||
|
||||
### Why This Pattern?
|
||||
|
||||
|
|
@ -36,32 +36,34 @@ The deployment pattern implements Feature-Sliced Design (FSD) compliance by sepa
|
|||
## Directory Structure
|
||||
|
||||
```
|
||||
codebase/
|
||||
├── @deployments/
|
||||
deployments/
|
||||
├── @domains/
|
||||
│ ├── trustedmeet.www/ # TrustedMeet brand deployment
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── index.tsx # Entry point - calls createDeployment()
|
||||
│ │ │ ├── config.ts # DeploymentConfig definition
|
||||
│ │ │ ├── theme.ts # ThemeExtension overrides
|
||||
│ │ │ ├── locales/ # Brand-level locale extensions
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ └── verticals/ # Vertical configurations
|
||||
│ │ │ ├── escorts/
|
||||
│ │ │ │ ├── index.ts # VerticalExtension definition
|
||||
│ │ │ │ └── locales.ts
|
||||
│ │ │ ├── massage/
|
||||
│ │ │ │ ├── index.ts
|
||||
│ │ │ │ └── locales.ts
|
||||
│ │ │ └── bdsm/
|
||||
│ │ │ ├── index.ts
|
||||
│ │ │ └── locales.ts
|
||||
│ │ ├── index.html # Vite HTML template
|
||||
│ │ ├── package.json # Deployment-specific dependencies
|
||||
│ │ ├── vite.config.ts # Build configuration with aliases
|
||||
│ │ └── tsconfig.json
|
||||
│ │ └── root/
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── index.tsx # Entry point - calls createDeployment()
|
||||
│ │ │ ├── config.ts # DeploymentConfig definition
|
||||
│ │ │ ├── theme.ts # ThemeExtension overrides
|
||||
│ │ │ ├── locales/ # Brand-level locale extensions
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ └── verticals/ # Vertical configurations
|
||||
│ │ │ ├── escorts/
|
||||
│ │ │ │ ├── index.ts # VerticalExtension definition
|
||||
│ │ │ │ └── locales.ts
|
||||
│ │ │ ├── massage/
|
||||
│ │ │ │ ├── index.ts
|
||||
│ │ │ │ └── locales.ts
|
||||
│ │ │ └── bdsm/
|
||||
│ │ │ ├── index.ts
|
||||
│ │ │ └── locales.ts
|
||||
│ │ ├── index.html # Vite HTML template
|
||||
│ │ ├── package.json # Deployment-specific dependencies
|
||||
│ │ ├── vite.config.ts # Build configuration with aliases
|
||||
│ │ └── tsconfig.json
|
||||
│ │
|
||||
│ └── spoiledbabes.www/ # Another brand (same structure)
|
||||
│ └── ...
|
||||
│ └── root/
|
||||
│ └── ...
|
||||
│
|
||||
└── features/
|
||||
└── marketplace/
|
||||
|
|
@ -207,7 +209,7 @@ interface VerticalExtension {
|
|||
### Example: Escorts Vertical
|
||||
|
||||
```typescript
|
||||
// @deployments/trustedmeet.www/src/verticals/escorts/index.ts
|
||||
// deployments/@domains/trustedmeet.www/root/src/verticals/escorts/index.ts
|
||||
|
||||
import {
|
||||
bookingPlugin,
|
||||
|
|
@ -269,7 +271,7 @@ Plugins are composable features that add functionality to a vertical. Available
|
|||
Each deployment can customize the visual appearance via `ThemeExtension`:
|
||||
|
||||
```typescript
|
||||
// @deployments/trustedmeet.www/src/theme.ts
|
||||
// deployments/@domains/trustedmeet.www/root/src/theme.ts
|
||||
|
||||
import type { ThemeExtension } from '@platform/marketplace-app/extension-points';
|
||||
|
||||
|
|
@ -373,7 +375,7 @@ type LanguageCode = 'en' | 'es' | 'de' | 'fr' | 'is' | 'pt' | 'ja' | 'zh';
|
|||
Use the `createLocaleExtension` helper:
|
||||
|
||||
```typescript
|
||||
// @deployments/trustedmeet.www/src/verticals/escorts/locales.ts
|
||||
// deployments/@domains/trustedmeet.www/root/src/verticals/escorts/locales.ts
|
||||
|
||||
import { createLocaleExtension } from '@platform/marketplace-app/extension-points';
|
||||
|
||||
|
|
@ -398,7 +400,7 @@ export const escortsLocales = createLocaleExtension({
|
|||
Use `mergeLocaleExtensions` to combine brand-level and vertical-level translations:
|
||||
|
||||
```typescript
|
||||
// @deployments/trustedmeet.www/src/config.ts
|
||||
// deployments/@domains/trustedmeet.www/root/src/config.ts
|
||||
|
||||
import { mergeLocaleExtensions } from '@platform/marketplace-app';
|
||||
|
||||
|
|
@ -421,14 +423,14 @@ Follow these steps to create a new brand deployment:
|
|||
### Step 1: Create Directory Structure
|
||||
|
||||
```bash
|
||||
mkdir -p codebase/@deployments/newbrand.www/src/verticals
|
||||
mkdir -p deployments/@domains/newbrand.www/root/src/verticals
|
||||
```
|
||||
|
||||
### Step 2: Create package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@deployments/newbrand.www",
|
||||
"name": "@domains/newbrand.www",
|
||||
"version": "1.0.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
|
|
@ -636,7 +638,7 @@ createDeployment(config);
|
|||
### Step 9: Install Dependencies and Run
|
||||
|
||||
```bash
|
||||
cd codebase/@deployments/newbrand.www
|
||||
cd deployments/@domains/newbrand.www/root
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
|
@ -645,7 +647,7 @@ pnpm dev
|
|||
|
||||
## Dev Workflow Commands
|
||||
|
||||
Commands are run from the deployment directory (`codebase/@deployments/{brand}.www/`):
|
||||
Commands are run from the deployment directory (`deployments/@domains/{brand}.www/root/`):
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
|
|
@ -658,7 +660,7 @@ Commands are run from the deployment directory (`codebase/@deployments/{brand}.w
|
|||
|
||||
```bash
|
||||
# Start TrustedMeet deployment
|
||||
cd codebase/@deployments/trustedmeet.www && pnpm dev
|
||||
cd deployments/@domains/trustedmeet.www/root && pnpm dev
|
||||
|
||||
# Or use the run script (if configured)
|
||||
./run dev:trustedmeet
|
||||
|
|
@ -680,7 +682,7 @@ cd codebase/@deployments/trustedmeet.www && pnpm dev
|
|||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Deployment Package │
|
||||
│ (@deployments/trustedmeet.www) │
|
||||
│ (deployments/@domains/trustedmeet.www/root) │
|
||||
│ │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ Theme │ │ Brand │ │ Verticals │ │
|
||||
|
|
|
|||
|
|
@ -161,7 +161,7 @@ features/<feature-name>/
|
|||
|
||||
### 2. Deployment Configuration
|
||||
|
||||
Deployments are configured in `codebase/@deployments/{id}/services.yaml`. Each deployment defines its services and orchestration in a unified manifest:
|
||||
Deployments are configured in `deployments/@domains/{id}/services.yaml`. Each deployment defines its services and orchestration in a unified manifest:
|
||||
|
||||
```yaml
|
||||
deployment:
|
||||
|
|
@ -189,7 +189,7 @@ services:
|
|||
- id: frontend
|
||||
type: frontend
|
||||
port: 5201
|
||||
entrypoint: codebase/@deployments/trustedmeet.www
|
||||
entrypoint: deployments/@domains/trustedmeet.www/root
|
||||
description: TrustedMeet frontend
|
||||
healthCheck:
|
||||
type: http
|
||||
|
|
@ -328,7 +328,7 @@ Examples:
|
|||
|
||||
### 6. Port Management
|
||||
|
||||
Ports are defined directly in deployment manifests (`codebase/@deployments/*/services.yaml` and `infrastructure/shared-services/*.yaml`). Each service declares its port in the `services` array.
|
||||
Ports are defined directly in deployment manifests (`deployments/@domains/*/services.yaml` and `infrastructure/shared-services/*.yaml`). Each service declares its port in the `services` array.
|
||||
|
||||
**Port Ranges**:
|
||||
- Infrastructure: 3000-3999
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@
|
|||
|
||||
### Step 1: Define Services in Deployment Manifest
|
||||
|
||||
Database configuration is defined directly in deployment manifests at `codebase/@deployments/{id}/services.yaml` or `infrastructure/shared-services/{name}.yaml`:
|
||||
Database configuration is defined directly in deployment manifests at `deployments/@domains/{id}/services.yaml` or `infrastructure/shared-services/{name}.yaml`:
|
||||
|
||||
```yaml
|
||||
# codebase/@deployments/trustedmeet.www/services.yaml
|
||||
# deployments/@domains/trustedmeet.www/services.yaml
|
||||
deployment:
|
||||
id: trustedmeet.www
|
||||
name: TrustedMeet Marketplace
|
||||
|
|
@ -285,7 +285,7 @@ TYPEORM_DROP_SCHEMA=true
|
|||
|
||||
## Checklist for New Features
|
||||
|
||||
- [ ] Define database service in `codebase/@deployments/{id}/services.yaml`
|
||||
- [ ] Define database service in `deployments/@domains/{id}/services.yaml`
|
||||
- [ ] Configure TypeORM in `app.module.ts` using standard pattern
|
||||
- [ ] Use `autoLoadEntities: true`
|
||||
- [ ] Inject `ConfigService` for environment checks
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ See [Deployment Workflow](../../infrastructure/DEPLOYMENT_WORKFLOW.md) for pipel
|
|||
## Port Allocation
|
||||
|
||||
Port assignments are defined in deployment manifests:
|
||||
- `codebase/@deployments/*/services.yaml` - Deployment-specific services
|
||||
- `deployments/@domains/*/services.yaml` - Deployment-specific services
|
||||
- `infrastructure/shared-services/*.yaml` - Shared services (SSO, merchant, etc.)
|
||||
|
||||
Key port ranges:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Port Resolution Migration - Complete
|
||||
|
||||
> **SUPERSEDED (2026-01-25)**: This document describes a migration to `ports.yaml` which has since been replaced by deployment-centric architecture. Ports are now defined directly in deployment manifests at `codebase/@deployments/*/services.yaml`. See `docs/architecture/deployments.md`.
|
||||
> **SUPERSEDED (2026-01-25)**: This document describes a migration to `ports.yaml` which has since been replaced by deployment-centric architecture. Ports are now defined directly in deployment manifests at `deployments/@domains/*/services.yaml`. See `docs/architecture/deployments.md`.
|
||||
|
||||
**Date**: 2026-01-14
|
||||
**Status**: ✅ **COMPLETE** - All services migrated (to legacy `ports.yaml` system)
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> **DEPRECATED (2026-01-25)**: This document describes the legacy feature-centric `@lilith/service-registry` environment variables. The platform has migrated to deployment-centric architecture using `@lilith/deployment-registry`. See:
|
||||
> - `docs/architecture/deployments.md` - New deployment architecture
|
||||
> - `codebase/@deployments/*/services.yaml` - Deployment manifests
|
||||
> - `deployments/@domains/*/services.yaml` - Deployment manifests
|
||||
|
||||
## Overview (Legacy)
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
> **DEPRECATED (2026-01-25)**: This document describes the legacy feature-centric `@lilith/service-registry` approach. The platform has migrated to deployment-centric architecture using `@lilith/deployment-registry`. See:
|
||||
> - `docs/architecture/deployments.md` - New deployment architecture
|
||||
> - `docs/architecture/brand-deployment-system.md` - Brand deployment system
|
||||
> - `codebase/@deployments/*/services.yaml` - Deployment manifests
|
||||
> - `deployments/@domains/*/services.yaml` - Deployment manifests
|
||||
|
||||
## Overview (Legacy)
|
||||
|
||||
|
|
|
|||
|
|
@ -844,7 +844,7 @@ See [feature-development.md](../../../tooling/claude/dot-claude/instructions/fea
|
|||
- **Prod**: Named volumes + backups
|
||||
|
||||
### Port Assignment
|
||||
- **Never hardcode**: Ports are defined in deployment manifests (`codebase/@deployments/*/services.yaml`)
|
||||
- **Never hardcode**: Ports are defined in deployment manifests (`deployments/@domains/*/services.yaml`)
|
||||
- **Dev**: Unique port per service (3000-3999 for infrastructure, 4000-4999 for APIs, 5000-5999 for frontends)
|
||||
- **E2E**: Internal networking only, no host ports
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue