@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/server-side/backend-architecture/TRUE-FINAL-ARCHITECTURE.md

@@ -0,0 +1,603 @@
+# THE TRUE OPTIMAL ARCHITECTURE ✅
+
+**Crystal Clear Now!** Store ObjectId references internally, expose UUIDs only through GraphQL resolution.
+
+---
+
+## 🎯 The Actual Pattern
+
+### Database Storage (MongoDB)
+
+```javascript
+// Application Document
+{
+  _id: ObjectId("507f1f77bcf86cd799439011"),      // Internal (never expose)
+  appId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",  // External UUID
+
+  // ObjectId references (MongoDB-optimized)
+  project: ObjectId("507f1f77bcf86cd799439012"),
+  tenant: ObjectId("507f1f77bcf86cd799439013"),
+  organization: ObjectId("507f1f77bcf86cd799439014"),
+
+  // Business data
+  name: "My Application",
+  status: "production",
+  createdAt: ISODate("2025-10-31T10:00:00Z"),
+  updatedAt: ISODate("2025-10-31T10:00:00Z")
+}
+```
+
+**Key Points:**
+
+- ✅ Only ONE reference field per relationship (`project`, not `project` + `projectId`)
+- ✅ References are ObjectId (MongoDB-optimized)
+- ✅ UUIDs exposed ONLY through GraphQL resolution
+
+---
+
+## 📋 Complete Schema
+
+```typescript
+// models/Application.ts
+import { Schema, model, Document } from 'mongoose';
+import { v4 as uuidv4 } from 'uuid';
+
+export interface IApplication extends Document {
+    _id: Schema.Types.ObjectId; // MongoDB internal
+    id: string; // Virtual → appId
+    appId: string; // External UUID
+
+    // ObjectId references (internal only)
+    project: Schema.Types.ObjectId;
+    tenant: Schema.Types.ObjectId;
+    organization: Schema.Types.ObjectId;
+
+    name: string;
+    status: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+const ApplicationSchema = new Schema<IApplication>(
+    {
+        // External UUID (only way to query from outside)
+        appId: {
+            type: String,
+            default: () => uuidv4(),
+            unique: true,
+            required: true,
+            index: true,
+            immutable: true,
+        },
+
+        // ObjectId references (internal, never exposed directly)
+        project: {
+            type: Schema.Types.ObjectId,
+            ref: 'Project',
+            required: true,
+            index: true,
+        },
+        tenant: {
+            type: Schema.Types.ObjectId,
+            ref: 'Tenant',
+            required: true,
+            index: true,
+        },
+        organization: {
+            type: Schema.Types.ObjectId,
+            ref: 'Organization',
+            required: true,
+            index: true,
+        },
+
+        // Business fields
+        name: {
+            type: String,
+            required: true,
+            trim: true,
+        },
+        status: {
+            type: String,
+            enum: ['development', 'staging', 'production', 'archived'],
+            default: 'development',
+        },
+    },
+    {
+        timestamps: true,
+        toJSON: {
+            virtuals: true,
+            transform: (doc, ret) => {
+                // Remove internal MongoDB fields
+                delete ret._id;
+                delete ret.__v;
+                // Remove ObjectId references (GraphQL will resolve these)
+                delete ret.project;
+                delete ret.tenant;
+                delete ret.organization;
+                return ret;
+            },
+        },
+        toObject: { virtuals: true },
+    },
+);
+
+// Virtual 'id' field
+ApplicationSchema.virtual('id').get(function () {
+    return this.appId;
+});
+
+// Indexes
+ApplicationSchema.index({ project: 1, status: 1 });
+ApplicationSchema.index({ tenant: 1 });
+
+export const Application = model<IApplication>('Application', ApplicationSchema);
+```
+
+---
+
+## 🎨 GraphQL Pattern
+
+### Type Definitions
+
+```graphql
+type Application {
+    id: ID! # appId (UUID)
+    name: String!
+    status: ApplicationStatus!
+
+    # These are RESOLVED via populate, exposing nested UUIDs
+    project: Project! # Resolves to { id, name, ... }
+    tenant: Tenant! # Resolves to { id, name, ... }
+    organization: Organization!
+
+    createdAt: DateTime!
+    updatedAt: DateTime!
+}
+
+type Project {
+    id: ID! # projectId (UUID)
+    name: String!
+    organization: Organization!
+}
+
+type Query {
+    # Query by UUID only
+    application(id: ID!): Application
+}
+
+input CreateApplicationInput {
+    # Client provides UUIDs
+    projectId: ID!
+    tenantId: ID!
+    name: String!
+}
+```
+
+### How Client Queries
+
+```graphql
+# Client queries by UUID (appId)
+query GetApplication {
+  application(id: "f47ac10b-58cc-4372-a567-0e02b2c3d479") {
+    id                    # Returns appId (UUID)
+    name
+    project {
+      id                  # Returns projectId (UUID)
+      name
+    }
+    tenant {
+      id                  # Returns tenantId (UUID)
+      name
+    }
+  }
+}
+
+# Response (all UUIDs, no ObjectIds!)
+{
+  "data": {
+    "application": {
+      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+      "name": "My Application",
+      "project": {
+        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+        "name": "My Project"
+      },
+      "tenant": {
+        "id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
+        "name": "Production Tenant"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 💻 GraphQL Resolvers
+
+```typescript
+// resolvers/application.ts
+import { Application } from '../models/Application';
+import { Project } from '../models/Project';
+
+export const applicationResolvers = {
+    Query: {
+        application: async (_, { id }: { id: string }) => {
+            // Query by UUID (appId)
+            return Application.findOne({ appId: id })
+                .populate('project') // Populate ObjectId reference
+                .populate('tenant') // Populate ObjectId reference
+                .populate('organization'); // Populate ObjectId reference
+        },
+    },
+
+    Mutation: {
+        createApplication: async (_, { input }, context) => {
+            // Step 1: Resolve input UUIDs to ObjectIds
+            const project = await Project.findOne({ projectId: input.projectId });
+            if (!project) throw new Error('Project not found');
+
+            const tenant = await Tenant.findOne({ tenantId: input.tenantId });
+            if (!tenant) throw new Error('Tenant not found');
+
+            // Step 2: Create with ObjectId references
+            const application = await Application.create({
+                appId: uuidv4(),
+                project: project._id, // Store ObjectId
+                tenant: tenant._id, // Store ObjectId
+                organization: project.organization, // Store ObjectId
+                name: input.name,
+            });
+
+            // Step 3: Return with populated refs
+            return Application.findById(application._id)
+                .populate('project')
+                .populate('tenant')
+                .populate('organization');
+        },
+    },
+
+    Application: {
+        // These resolvers expose UUIDs from populated documents
+        project: (parent) => {
+            // If already populated, it has projectId
+            // toJSON will expose only the projectId as 'id'
+            return parent.project; // Returns populated Project with projectId
+        },
+
+        tenant: (parent) => {
+            return parent.tenant; // Returns populated Tenant with tenantId
+        },
+
+        organization: (parent) => {
+            return parent.organization; // Returns populated Org with organizationId
+        },
+    },
+};
+```
+
+---
+
+## 🔄 The Data Flow
+
+### 1. Client Queries Application
+
+```
+Client Request (GraphQL):
+  application(id: "uuid-app")
+
+↓
+
+GraphQL Resolver:
+  Application.findOne({ appId: "uuid-app" })
+    .populate('project')
+    .populate('tenant')
+
+↓
+
+MongoDB Query:
+  1. Find application by appId (UUID)
+  2. Populate project using ObjectId reference (fast!)
+  3. Populate tenant using ObjectId reference (fast!)
+
+↓
+
+Response to Client (all UUIDs):
+  {
+    id: "uuid-app",
+    project: { id: "uuid-project", name: "..." },
+    tenant: { id: "uuid-tenant", name: "..." }
+  }
+```
+
+### 2. Client Creates Application
+
+```
+Client Request (GraphQL):
+  createApplication(input: {
+    projectId: "uuid-project",
+    tenantId: "uuid-tenant",
+    name: "My App"
+  })
+
+↓
+
+GraphQL Resolver:
+  1. Find Project by projectId (UUID)
+  2. Find Tenant by tenantId (UUID)
+  3. Create Application with ObjectId references
+
+↓
+
+MongoDB:
+  Application.create({
+    appId: uuidv4(),
+    project: ObjectId('507f...'),     // ObjectId reference
+    tenant: ObjectId('507f...'),      // ObjectId reference
+    organization: ObjectId('507f...'),
+    name: "My App"
+  })
+
+↓
+
+Response to Client:
+  {
+    id: "uuid-app",
+    project: { id: "uuid-project", name: "..." },
+    tenant: { id: "uuid-tenant", name: "..." }
+  }
+```
+
+---
+
+## 📊 Project Collection Schema
+
+```typescript
+const ProjectSchema = new Schema(
+    {
+        // External UUID (only way to query from outside)
+        projectId: {
+            type: String,
+            default: () => uuidv4(),
+            unique: true,
+            required: true,
+        },
+
+        // ObjectId reference (internal)
+        organization: {
+            type: Schema.Types.ObjectId,
+            ref: 'Organization',
+            required: true,
+        },
+
+        name: String,
+        status: String,
+    },
+    {
+        toJSON: {
+            virtuals: true,
+            transform: (doc, ret) => {
+                delete ret._id;
+                delete ret.organization; // Hide ObjectId reference
+                return ret;
+            },
+        },
+    },
+);
+
+ProjectSchema.virtual('id').get(function () {
+    return this.projectId;
+});
+```
+
+---
+
+## 🎯 Key Principles
+
+### ✅ What We Store
+
+```typescript
+{
+  appId: String (UUID),          // External identifier
+  project: ObjectId,             // Internal reference (MongoDB-optimized)
+  tenant: ObjectId,              // Internal reference (MongoDB-optimized)
+  organization: ObjectId         // Internal reference (MongoDB-optimized)
+}
+```
+
+### ✅ What Client Sees
+
+```graphql
+{
+  id: "uuid-app"                 # appId
+  project {
+    id: "uuid-project"           # projectId (from populated doc)
+    name: "..."
+  }
+  tenant {
+    id: "uuid-tenant"            # tenantId (from populated doc)
+    name: "..."
+  }
+}
+```
+
+### ✅ The Magic
+
+- **Storage:** ObjectId references (MongoDB-optimized, fast joins)
+- **Exposure:** UUIDs only (via GraphQL resolution)
+- **No duplication:** Single source of truth per reference
+- **Fast queries:** ObjectId populate is native and fast
+- **Clean APIs:** Client never sees ObjectIds
+
+---
+
+## 💡 Why This is Perfect
+
+| Benefit                | How                                 |
+| ---------------------- | ----------------------------------- |
+| **Fast MongoDB Joins** | ObjectId references + populate      |
+| **Clean API**          | UUIDs exposed via GraphQL           |
+| **No Duplication**     | One field per reference             |
+| **Simple Schema**      | Straightforward document structure  |
+| **GraphQL Native**     | Resolvers handle the transformation |
+
+---
+
+## ⚠️ What About Database Migration?
+
+When migrating to PostgreSQL:
+
+### MongoDB
+
+```javascript
+{
+  _id: ObjectId('507f...'),
+  appId: 'uuid',
+  project: ObjectId('507f...'),  // MongoDB reference
+  name: 'My App'
+}
+```
+
+### PostgreSQL
+
+```sql
+CREATE TABLE applications (
+  _id SERIAL PRIMARY KEY,
+  app_id UUID UNIQUE,
+  project INTEGER REFERENCES projects(_id),  -- PostgreSQL reference
+  name VARCHAR(200)
+);
+```
+
+**Migration Steps:**
+
+1. ObjectId references → Integer references
+2. Keep the same GraphQL resolvers
+3. Update queries to use integer joins instead of ObjectId
+4. UUIDs (appId, projectId) stay exactly the same!
+
+---
+
+## 🚀 Service Layer
+
+```typescript
+export class ApplicationService {
+    async create(input: CreateApplicationInput): Promise<IApplication> {
+        // Resolve UUID to ObjectId
+        const project = await Project.findOne({ projectId: input.projectId });
+        if (!project) throw new NotFoundError('Project not found');
+
+        const tenant = await Tenant.findOne({ tenantId: input.tenantId });
+        if (!tenant) throw new NotFoundError('Tenant not found');
+
+        // Create with ObjectId references
+        return Application.create({
+            appId: uuidv4(),
+            project: project._id, // ObjectId
+            tenant: tenant._id, // ObjectId
+            organization: project.organization, // ObjectId
+            name: input.name,
+        });
+    }
+
+    async findById(appId: string): Promise<IApplication | null> {
+        return Application.findOne({ appId }).populate('project').populate('tenant').populate('organization');
+    }
+}
+```
+
+---
+
+## 📋 Complete Example
+
+### MongoDB Collections
+
+```javascript
+// Organizations
+{
+  _id: ObjectId('org1'),
+  organizationId: 'uuid-org-1',
+  name: 'Acme Corp'
+}
+
+// Projects
+{
+  _id: ObjectId('proj1'),
+  projectId: 'uuid-proj-1',
+  organization: ObjectId('org1'),  // ObjectId reference
+  name: 'Mobile App'
+}
+
+// Applications
+{
+  _id: ObjectId('app1'),
+  appId: 'uuid-app-1',
+  project: ObjectId('proj1'),       // ObjectId reference
+  tenant: ObjectId('tenant1'),      // ObjectId reference
+  organization: ObjectId('org1'),   // ObjectId reference
+  name: 'Production App'
+}
+```
+
+### GraphQL Query
+
+```graphql
+query {
+    application(id: "uuid-app-1") {
+        id # uuid-app-1
+        name # Production App
+        project {
+            id # uuid-proj-1 (from populated project)
+            name # Mobile App
+            organization {
+                id # uuid-org-1 (from populated org)
+                name # Acme Corp
+            }
+        }
+    }
+}
+```
+
+---
+
+## ✅ Final Summary
+
+### Storage Strategy
+
+- `_id`: Database-native (ObjectId in MongoDB)
+- `<entity>Id`: External UUID (appId, projectId, tenantId)
+- References: ObjectId (fast, MongoDB-optimized)
+
+### Exposure Strategy
+
+- Entry point: Query by UUID (`appId`, `projectId`, etc.)
+- References: Populated via GraphQL, expose nested UUIDs
+- Client sees: Only UUIDs, never ObjectIds
+
+### Benefits
+
+1. ✅ **Fast MongoDB joins** (ObjectId populate)
+2. ✅ **No data duplication** (one field per reference)
+3. ✅ **Clean APIs** (UUIDs only via GraphQL)
+4. ✅ **Simple schemas** (straightforward structure)
+5. ✅ **GraphQL-native** (resolvers handle transformation)
+
+---
+
+## 🎯 The Rule
+
+```
+STORE: ObjectId references (database-optimized)
+EXPOSE: UUIDs via GraphQL resolution (API-friendly)
+```
+
+**Perfect balance of performance and clean APIs!** 🎉
+
+---
+
+**This is the true optimal architecture!**
+
+- Internal: Fast ObjectId references
+- External: Clean UUID exposure
+- No duplication
+- GraphQL handles the magic ✨