@xbg.solutions/create-backend 1.0.0

package/src/project-template/__examples__/blog-platform.model.ts

@@ -0,0 +1,528 @@
+/**
+ * Blog Platform Data Model
+ *
+ * A complete blog platform with:
+ * - User authentication and profiles
+ * - Posts with categories and tags
+ * - Comments with threading
+ * - Social features (likes, follows)
+ * - Content moderation
+ *
+ * Features demonstrated:
+ * - One-to-many relationships (User → Posts)
+ * - Many-to-many relationships (Posts → Tags)
+ * - Self-referencing relationships (Comment replies)
+ * - Access control rules
+ * - Business rules and validation
+ * - Optimized indexes
+ *
+ * To use this model:
+ * 1. Copy to your project
+ * 2. Run: npm run generate __examples__/blog-platform.model.ts
+ * 3. Register controllers in functions/src/app.ts
+ * 4. Deploy: npm run deploy
+ */
+
+import { DataModelSpecification } from '../functions/src/generator/types';
+
+export const BlogPlatformModel: DataModelSpecification = {
+  entities: {
+    User: {
+      fields: {
+        email: {
+          type: 'email',
+          unique: true,
+          required: true,
+        },
+        username: {
+          type: 'string',
+          unique: true,
+          required: true,
+        },
+        displayName: {
+          type: 'string',
+          required: true,
+        },
+        bio: {
+          type: 'text',
+          required: false,
+        },
+        avatarUrl: {
+          type: 'url',
+          required: false,
+        },
+        isVerified: {
+          type: 'boolean',
+          default: false,
+        },
+        role: {
+          type: 'enum',
+          values: ['reader', 'author', 'moderator', 'admin'],
+          default: 'reader',
+        },
+        status: {
+          type: 'enum',
+          values: ['active', 'suspended', 'deleted'],
+          default: 'active',
+        },
+        lastLoginAt: {
+          type: 'timestamp',
+          required: false,
+        },
+        createdAt: {
+          type: 'timestamp',
+          required: true,
+        },
+        updatedAt: {
+          type: 'timestamp',
+          required: true,
+        },
+      },
+      relationships: {
+        posts: {
+          type: 'one-to-many',
+          entity: 'Post',
+          foreignKey: 'authorId',
+          cascadeDelete: false, // Keep posts when user is deleted (anonymize instead)
+        },
+        comments: {
+          type: 'one-to-many',
+          entity: 'Comment',
+          foreignKey: 'authorId',
+          cascadeDelete: false,
+        },
+        likedPosts: {
+          type: 'many-to-many',
+          entity: 'Post',
+          through: 'PostLike',
+        },
+        following: {
+          type: 'many-to-many',
+          entity: 'User',
+          through: 'UserFollow',
+          foreignKey: 'followerId',
+          relatedKey: 'followingId',
+        },
+      },
+      access: {
+        create: ['public'], // Public registration
+        read: ['public'],
+        update: ['self', 'admin'],
+        delete: ['self', 'admin'],
+      },
+      validation: {
+        email: 'Must be a valid email address',
+        username: 'Must be 3-30 characters, alphanumeric and underscores only',
+        displayName: 'Must be 1-100 characters',
+      },
+      businessRules: [
+        'Email must be verified before user can publish posts',
+        'Suspended users cannot create posts or comments',
+        'Deleted users have their personal data anonymized',
+        'Users cannot follow themselves',
+      ],
+      indexes: [
+        { fields: ['email'], unique: true },
+        { fields: ['username'], unique: true },
+        { fields: ['status'] },
+        { fields: ['createdAt'] },
+      ],
+    },
+
+    Post: {
+      fields: {
+        title: {
+          type: 'string',
+          required: true,
+        },
+        slug: {
+          type: 'string',
+          unique: true,
+          required: true,
+        },
+        content: {
+          type: 'text',
+          required: true,
+        },
+        excerpt: {
+          type: 'string',
+          required: false,
+        },
+        coverImageUrl: {
+          type: 'url',
+          required: false,
+        },
+        status: {
+          type: 'enum',
+          values: ['draft', 'published', 'archived', 'flagged'],
+          default: 'draft',
+        },
+        publishedAt: {
+          type: 'timestamp',
+          required: false,
+        },
+        authorId: {
+          type: 'reference',
+          entity: 'User',
+          required: true,
+        },
+        categoryId: {
+          type: 'reference',
+          entity: 'Category',
+          required: true,
+        },
+        viewCount: {
+          type: 'number',
+          default: 0,
+        },
+        likeCount: {
+          type: 'number',
+          default: 0,
+        },
+        commentCount: {
+          type: 'number',
+          default: 0,
+        },
+        readingTimeMinutes: {
+          type: 'number',
+          required: false,
+        },
+        isFeatured: {
+          type: 'boolean',
+          default: false,
+        },
+        createdAt: {
+          type: 'timestamp',
+          required: true,
+        },
+        updatedAt: {
+          type: 'timestamp',
+          required: true,
+        },
+      },
+      relationships: {
+        author: {
+          type: 'many-to-one',
+          entity: 'User',
+        },
+        category: {
+          type: 'many-to-one',
+          entity: 'Category',
+        },
+        comments: {
+          type: 'one-to-many',
+          entity: 'Comment',
+          foreignKey: 'postId',
+          cascadeDelete: true,
+        },
+        tags: {
+          type: 'many-to-many',
+          entity: 'Tag',
+          through: 'PostTag',
+        },
+        likes: {
+          type: 'many-to-many',
+          entity: 'User',
+          through: 'PostLike',
+        },
+      },
+      access: {
+        create: ['author', 'admin'],
+        read: ['public'], // Anyone can read published posts
+        update: ['self', 'admin'],
+        delete: ['self', 'admin'],
+      },
+      validation: {
+        title: 'Must be 5-200 characters',
+        slug: 'Must be URL-safe and unique',
+        content: 'Must not be empty',
+      },
+      businessRules: [
+        'Slug is auto-generated from title',
+        'Published posts cannot be unpublished (only archived)',
+        'Posts must belong to an active category',
+        'Reading time is calculated from content length',
+        'Only verified users can publish posts',
+      ],
+      indexes: [
+        { fields: ['slug'], unique: true },
+        { fields: ['authorId', 'status'] },
+        { fields: ['categoryId', 'status'] },
+        { fields: ['status', 'publishedAt'] },
+        { fields: ['isFeatured', 'publishedAt'] },
+      ],
+    },
+
+    Comment: {
+      fields: {
+        content: {
+          type: 'text',
+          required: true,
+        },
+        postId: {
+          type: 'reference',
+          entity: 'Post',
+          required: true,
+        },
+        authorId: {
+          type: 'reference',
+          entity: 'User',
+          required: true,
+        },
+        parentId: {
+          type: 'reference',
+          entity: 'Comment',
+          required: false,
+        },
+        status: {
+          type: 'enum',
+          values: ['visible', 'flagged', 'deleted'],
+          default: 'visible',
+        },
+        isEdited: {
+          type: 'boolean',
+          default: false,
+        },
+        createdAt: {
+          type: 'timestamp',
+          required: true,
+        },
+        updatedAt: {
+          type: 'timestamp',
+          required: true,
+        },
+      },
+      relationships: {
+        post: {
+          type: 'many-to-one',
+          entity: 'Post',
+        },
+        author: {
+          type: 'many-to-one',
+          entity: 'User',
+        },
+        parent: {
+          type: 'many-to-one',
+          entity: 'Comment',
+          optional: true,
+        },
+        replies: {
+          type: 'one-to-many',
+          entity: 'Comment',
+          foreignKey: 'parentId',
+          cascadeDelete: true,
+        },
+      },
+      access: {
+        create: ['authenticated'],
+        read: ['public'],
+        update: ['self', 'moderator', 'admin'],
+        delete: ['self', 'moderator', 'admin'],
+      },
+      validation: {
+        content: 'Must be 1-2000 characters',
+      },
+      businessRules: [
+        'Comments can be nested up to 3 levels deep',
+        'Deleted comments show [deleted] placeholder',
+        'Flagged comments are hidden from public view',
+        'Users can edit comments within 5 minutes of posting',
+      ],
+      indexes: [
+        { fields: ['postId', 'status', 'createdAt'] },
+        { fields: ['authorId'] },
+        { fields: ['parentId'] },
+      ],
+    },
+
+    Category: {
+      fields: {
+        name: {
+          type: 'string',
+          unique: true,
+          required: true,
+        },
+        slug: {
+          type: 'string',
+          unique: true,
+          required: true,
+        },
+        description: {
+          type: 'text',
+          required: false,
+        },
+        color: {
+          type: 'string',
+          required: false,
+        },
+        icon: {
+          type: 'string',
+          required: false,
+        },
+        isActive: {
+          type: 'boolean',
+          default: true,
+        },
+        postCount: {
+          type: 'number',
+          default: 0,
+        },
+        order: {
+          type: 'number',
+          default: 0,
+        },
+      },
+      relationships: {
+        posts: {
+          type: 'one-to-many',
+          entity: 'Post',
+          foreignKey: 'categoryId',
+        },
+      },
+      access: {
+        create: ['admin'],
+        read: ['public'],
+        update: ['admin'],
+        delete: ['admin'],
+      },
+      validation: {
+        name: 'Must be 2-50 characters',
+        slug: 'Must be URL-safe',
+      },
+      businessRules: [
+        'Categories with posts cannot be deleted',
+        'At least one category must exist',
+      ],
+      indexes: [
+        { fields: ['slug'], unique: true },
+        { fields: ['isActive', 'order'] },
+      ],
+    },
+
+    Tag: {
+      fields: {
+        name: {
+          type: 'string',
+          unique: true,
+          required: true,
+        },
+        slug: {
+          type: 'string',
+          unique: true,
+          required: true,
+        },
+        postCount: {
+          type: 'number',
+          default: 0,
+        },
+      },
+      relationships: {
+        posts: {
+          type: 'many-to-many',
+          entity: 'Post',
+          through: 'PostTag',
+        },
+      },
+      access: {
+        create: ['author', 'admin'],
+        read: ['public'],
+        update: ['admin'],
+        delete: ['admin'],
+      },
+      validation: {
+        name: 'Must be 2-30 characters',
+      },
+      businessRules: [
+        'Tags are automatically created when used in posts',
+        'Tags with zero posts are periodically cleaned up',
+      ],
+      indexes: [
+        { fields: ['slug'], unique: true },
+        { fields: ['postCount'] },
+      ],
+    },
+
+    PostLike: {
+      fields: {
+        postId: {
+          type: 'reference',
+          entity: 'Post',
+          required: true,
+        },
+        userId: {
+          type: 'reference',
+          entity: 'User',
+          required: true,
+        },
+        createdAt: {
+          type: 'timestamp',
+          required: true,
+        },
+      },
+      access: {
+        create: ['authenticated'],
+        read: ['public'],
+        delete: ['self'],
+      },
+      businessRules: [
+        'Users cannot like their own posts',
+        'Users can only like a post once',
+      ],
+      indexes: [
+        { fields: ['postId', 'userId'], unique: true },
+        { fields: ['userId'] },
+      ],
+    },
+
+    UserFollow: {
+      fields: {
+        followerId: {
+          type: 'reference',
+          entity: 'User',
+          required: true,
+        },
+        followingId: {
+          type: 'reference',
+          entity: 'User',
+          required: true,
+        },
+        createdAt: {
+          type: 'timestamp',
+          required: true,
+        },
+      },
+      access: {
+        create: ['authenticated'],
+        read: ['public'],
+        delete: ['self'],
+      },
+      businessRules: [
+        'Users cannot follow themselves',
+        'Users can only follow once (no duplicates)',
+      ],
+      indexes: [
+        { fields: ['followerId', 'followingId'], unique: true },
+        { fields: ['followingId'] },
+      ],
+    },
+
+    PostTag: {
+      fields: {
+        postId: {
+          type: 'reference',
+          entity: 'Post',
+          required: true,
+        },
+        tagId: {
+          type: 'reference',
+          entity: 'Tag',
+          required: true,
+        },
+      },
+      indexes: [
+        { fields: ['postId', 'tagId'], unique: true },
+        { fields: ['tagId'] },
+      ],
+    },
+  },
+};

package/src/project-template/__examples__/communications-usage.ts

@@ -0,0 +1,175 @@
+/**
+ * Communication Utilities Usage Examples
+ * Demonstrates how to use SNS, Email, SMS, and CRM connectors
+ */
+
+import {
+  getSNSConnector,
+  getEmailConnector,
+  getSMSConnector,
+  getCRMConnector,
+} from '../functions/src/utilities';
+
+/**
+ * Example 1: Publish event to SNS
+ */
+export async function exampleSNSPublish() {
+  const snsConnector = getSNSConnector();
+  if (!snsConnector) {
+    console.log('SNS connector not configured');
+    return;
+  }
+
+  await snsConnector.publishEvent(
+    process.env.SNS_USER_EVENTS_TOPIC!,
+    {
+      eventType: 'USER_REGISTERED',
+      entityType: 'User',
+      entityId: 'user-123',
+      data: {
+        email: 'user@example.com',
+        name: 'John Doe',
+      },
+      metadata: {
+        timestamp: new Date(),
+        correlationId: 'req-456',
+        userId: 'user-123',
+        source: 'web-app',
+        version: '1.0',
+      },
+    }
+  );
+}
+
+/**
+ * Example 2: Send transactional email
+ */
+export async function exampleSendWelcomeEmail() {
+  const emailConnector = getEmailConnector();
+  if (!emailConnector) {
+    console.log('Email connector not configured');
+    return;
+  }
+
+  await emailConnector.sendTransactional({
+    to: [
+      {
+        email: 'user@example.com',
+        name: 'John Doe',
+      },
+    ],
+    templateId: 'welcome-email',
+    variables: {
+      firstName: 'John',
+      activationLink: 'https://app.example.com/activate/token123',
+    },
+    tags: ['welcome', 'onboarding'],
+  });
+}
+
+/**
+ * Example 3: Send verification SMS
+ */
+export async function exampleSendVerificationSMS() {
+  const smsConnector = getSMSConnector();
+  if (!smsConnector) {
+    console.log('SMS connector not configured');
+    return;
+  }
+
+  const verificationCode = '123456';
+
+  await smsConnector.sendMessage({
+    to: '+1234567890',
+    message: `Your verification code is: ${verificationCode}. Valid for 10 minutes.`,
+    validityPeriod: 600, // 10 minutes
+    tags: ['verification', 'auth'],
+  });
+}
+
+/**
+ * Example 4: Sync user to CRM
+ */
+export async function exampleSyncUserToCRM() {
+  const crmConnector = getCRMConnector();
+  if (!crmConnector) {
+    console.log('CRM connector not configured');
+    return;
+  }
+
+  await crmConnector.createContact({
+    email: 'user@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+    phone: '+1234567890',
+    company: 'Acme Inc',
+    jobTitle: 'Software Engineer',
+    customFields: {
+      signup_date: new Date().toISOString(),
+      user_tier: 'premium',
+      referral_source: 'organic',
+    },
+    tags: ['new-user', 'premium'],
+    source: 'web_app',
+  });
+}
+
+/**
+ * Example 5: Log activity in CRM
+ */
+export async function exampleLogCRMActivity() {
+  const crmConnector = getCRMConnector();
+  if (!crmConnector) return;
+
+  await crmConnector.logActivity({
+    contactEmail: 'user@example.com',
+    type: 'purchase',
+    subject: 'Premium Plan Purchase',
+    description: 'User upgraded to premium plan for $99/month',
+    timestamp: new Date(),
+    customFields: {
+      plan_name: 'Premium',
+      plan_price: 99,
+      billing_cycle: 'monthly',
+    },
+  });
+}
+
+/**
+ * Example 6: Event-driven communication flow
+ * This shows how the event bus automatically triggers communications
+ */
+export async function exampleEventDrivenFlow() {
+  // When a USER_CREATED event is published to the event bus,
+  // the communication subscribers automatically:
+  // 1. Stream the event to SNS
+  // 2. Send a welcome email
+  // 3. Create a contact in CRM
+
+  // No manual connector calls needed - just publish the event!
+  // See: functions/src/subscribers/communication-subscribers.ts
+}
+
+/**
+ * Example 7: Bulk operations
+ */
+export async function exampleBulkOperations() {
+  const emailConnector = getEmailConnector();
+  if (!emailConnector) return;
+
+  const users = [
+    { email: 'user1@example.com', name: 'User 1' },
+    { email: 'user2@example.com', name: 'User 2' },
+    { email: 'user3@example.com', name: 'User 3' },
+  ];
+
+  await emailConnector.sendBulk({
+    emails: users.map((user) => ({
+      to: [user],
+      subject: 'Product Update',
+      htmlContent: '<h1>New Features Available!</h1>',
+      tags: ['product-update', 'marketing'],
+    })),
+    batchSize: 50,
+  });
+}