{"id":31848748,"url":"https://github.com/recker-dev/minicrm-backend","last_synced_at":"2026-07-19T17:33:30.750Z","repository":{"id":315026111,"uuid":"1054035313","full_name":"Recker-Dev/MiniCRM-backend","owner":"Recker-Dev","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-16T07:49:21.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-19T11:33:56.148Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Recker-Dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-10T09:20:58.000Z","updated_at":"2025-09-16T07:49:25.000Z","dependencies_parsed_at":"2025-09-17T16:05:23.830Z","dependency_job_id":null,"html_url":"https://github.com/Recker-Dev/MiniCRM-backend","commit_stats":null,"previous_names":["recker-dev/minicrm-backend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Recker-Dev/MiniCRM-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recker-Dev%2FMiniCRM-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recker-Dev%2FMiniCRM-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recker-Dev%2FMiniCRM-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recker-Dev%2FMiniCRM-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Recker-Dev","download_url":"https://codeload.github.com/Recker-Dev/MiniCRM-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Recker-Dev%2FMiniCRM-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35661225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-19T02:00:06.923Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-12T10:50:54.793Z","updated_at":"2026-07-19T17:33:30.744Z","avatar_url":"https://github.com/Recker-Dev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MiniCRM Prototype\n[View this repository on GitHub For Local Deployment Guide](https://github.com/Recker-Dev/MiniCRM-Deployment)\n## Overview\n\nThis repository contains the **technical prototype** of a lightweight CRM system built on a microservices architecture. It demonstrates **data ingestion**, **audience segmentation**, **campaign execution**, **Kafka-based asynchronous processing**, and **AI-assisted features**.  \n\nThe system is composed of the following services:\n\n- **Data Ingestion Faker** → Generates artificial `Customer` and `Order` data.\n- **MiniCRM Backend** → Core backend handling REST APIs, campaigns, and Kafka producers/consumers.\n- **Vendor Faker** → Simulates external delivery vendors with randomized outcomes.\n- **Frontend** → User interface for campaign management, segmentation, and history tracking.\n\n---\n\n\n# 🏗️ System Architecture\n\nThe MiniCRM project follows a **microservices-driven event-based architecture**, where services communicate asynchronously using **Kafka** as the backbone.  \n\n---\n\n## 🔑 Core Components\n\n- **MiniCRM Backend (`minicrm_backend`)**\n  - Exposes all REST endpoints (Customers, Orders, Campaigns, Users, Logs, Receipts, AI).\n  - Only service directly integrated with **Kafka**.\n  - Responsible for campaign orchestration and async updates.\n\n- **Data Ingestion Faker (`data_injestion_faker`)**\n  - Simulates customer and order data streams.\n  - Publishes mock records to Kafka (`customer-topic`, `order-topic`).\n\n- **Vendor Backend (`vendor_faker`)**\n  - Emulates a third-party vendor delivering campaign communications.\n  - Randomizes `success` / `fail` outcomes (10% failure chance).\n  - Reports results back via **Receipts API**.\n\n- **PostgreSQL Database**\n  - Central data store for **Customers, Orders, Campaigns, Communication Logs, and Users**.\n  - Accessed through Prisma ORM.\n\n- **Kafka Topics**\n  - Backbone for inter-service async communication:\n    - `customer-topic` → Customer ingestion.\n    - `order-topic` → Order ingestion.\n    - `campaign-deliveries` → Campaign execution batches.\n    - `deliveries-receipt` → Vendor delivery outcomes.\n\n---\n\n## 📊 Data Flow\n\n### 1. Data Ingestion\n[Data Ingestion Faker] → (customer-topic / order-topic) → [MiniCRM Backend] → [Postgres DB]\n- Customers \u0026 orders are published into Kafka.  \n- Backend consumers persist data into Postgres.  \n\n---\n\n### 2. Campaign Trigger\n[Frontend] → (POST /campaigns) → [MiniCRM Backend]\n- Request body includes `ruleGroup` (segmentation criteria).  \n- Backend:\n  - Converts `ruleGroup` into Prisma `where` clause.  \n  - AI module generates campaign **intent**.  \n  - Shortlisted customers are published to `campaign-deliveries`.  \n  - Campaign record created in DB.  \n  - API response returns **campaign ticket**.  \n---\n\n### 3. Campaign Delivery\n[campaign-deliveries Topic] → [Vendor Backend] → External Vendor (simulated)\n- Vendor Faker consumes batches of campaign customers.  \n- For each message:\n  - Simulates delivery (`success` or `fail`).  \n  - Sends POST `/receipts` → MiniCRM Backend.  \n\n---\n\n### 4. Receipt Processing\n\n[Vendor Backend] → (POST /receipts) → [MiniCRM Backend] → (deliveries-receipt Topic)\n- Receipts are **quickly enqueued** into Kafka (`deliveries-receipt`).  \n- Async consumer processes them:\n  - Updates `Communication_log`.  \n  - Adjusts `sent_count` / `failed_count` in Campaign.  \n  - On last receipt → triggers **AI summarizer** to finalize campaign insights.  \n\n---\n\n## ⚡ Key Design Principles\n\n- **Async-first** → Kafka buffers ensure resilient, decoupled services.  \n- **Batch Processing** → Consumers process records in chunks for efficiency.  \n- **Fail-Safe Vendor Simulation** → Vendor failures are randomized for realism.  \n- **DB Consistency via Prisma** → All campaign \u0026 communication logs are updated transactionally.  \n- **AI Integration** → Provides campaign intent detection \u0026 summary generation.  \n\n---\n\n\n## Setup Instructions\n\nTo run the system, **4 terminals** are required.\n\n### 1. Data Ingestion Faker\n```bash\ncd data_injestion_faker\nnpm install\nnode index.js\n```\n- Comment/uncomment the appropriate start functions in index.js to switch between:\n\n  - Customer Generator\n\n  - Order Generator\n\n### 2. Vendor Backend\n```bash\ncd vendor_faker\nnpm install\nnode index.js\n```\n- Runs on port 3500.\n\n- Simulates vendor delivery attempts and reports results back to the backend via receipts.\n\n### 3. MiniCRM Backend\nTwo terminals are needed:\n#### Terminal A – Start HTTP Server \u0026 Kafka Producer\n```bash\ncd minicrm_backend\nnpm install\nnode index.js\n```\n- Runs on port 3000.\n\n#### Terminal B – Start Kafka Consumers\n```bash\nnode consumer.js\n```\n- Handles background processing for campaign deliveries and receipts.\n\n\n## Kafka\n\nKafka is the backbone of this system, enabling asynchronous communication between microservices. The topics are initialized in `config/kafkaInit.js`.\n\n### Defined Topics\n- **`customer-topic`**  \n  Carries validated customer data from the **Data Ingestion Faker** before bulk insertion into the database.\n\n- **`order-topic`**  \n  Carries validated order data from the **Data Ingestion Faker** before bulk insertion into the database.\n\n- **`campaign-deliveries`**  \n  Holds campaign-triggered customer batches that are queued for delivery via the **Vendor Faker**.\n\n- **`deliveries-receipt`**  \n  Receives vendor delivery outcomes (`success` / `fail`) which are then processed into the **Communication Log** and campaign status updates.\n\n---\n\n## Database and  Schema\n\nThe system uses **PostgreSQL** as the primary database. Prisma ORM is used for schema management and queries.  \nThe schema models represent the CRM domain: customers, orders, campaigns, communications, and users.\n\n---\n\n### Customer\nRepresents an individual customer in the CRM.\n\n```prisma\nmodel Customer {\n  id                String              @id @default(uuid())\n  name              String\n  email             String              @unique\n  phone             String?             @unique\n  city              String?\n  total_spend       Float               @default(0)\n  visit             Int                 @default(0)\n  last_order_date   DateTime?\n  createdAt         DateTime            @default(now())\n  orders            Order[]\n  communication_log Communication_log[]\n}\n```\n\n### Order\nRepresents a customer order.\n\n```prisma\nmodel Order {\n  id         String      @id @default(uuid())\n  customer   Customer    @relation(fields: [customerId], references: [id], onDelete: Cascade)\n  customerId String\n  order_date DateTime    @default(now())\n  amount     Float\n  status     OrderStatus @default(PENDING)\n  items      OrderItem[]\n}\n```\n\n### Campaign\nRepresents a marketing campaign targeting specific customer segments.\n\n```prisma\nmodel Campaign {\n  id                String              @id @default(uuid())\n  name              String\n  userId            String\n  intent            String\n  segment           Json\n  summary           String?\n  audience_size     Int\n  message           String\n  status            CampaignStatus      @default(RUNNING)\n  pending_count     Int                 @default(0)\n  sent_count        Int                 @default(0)\n  failed_count      Int                 @default(0)\n  createdAt         DateTime            @default(now())\n  communication_log Communication_log[]\n}\n```\n### Campaign\nTracks message delivery status for each customer in a campaign.\n\n```prisma\nmodel Communication_log {\n  id         String   @id @default(uuid())\n  campaign   Campaign @relation(fields: [campaignId], references: [id], onDelete: Cascade)\n  campaignId String\n  customer   Customer @relation(fields: [customerId], references: [id], onDelete: Cascade)\n  customerId String\n\n  customer_name    String\n  email            String\n  phone            String?\n  personalized_msg String\n\n  status DeliveryStatus @default(PENDING)\n\n  delivered_at DateTime?\n  createdAt    DateTime  @default(now())\n}\n```\n### User\nRepresents a CRM user authenticated via Google OAuth.\n\n```prisma\nmodel User {\n  id        String   @id @default(dbgenerated(\"concat('user_', replace(cast(gen_random_uuid() as text), '-', ''))\"))\n  googleId  String?  @unique\n  email     String?  @unique\n  name      String?\n  avatar    String?\n  createdAt DateTime @default(now())\n  updatedAt DateTime @updatedAt\n}\n\n```\n\n## Notes\n\n- **Kafka \u0026 Zookeeper** must be running locally before starting any services.  \n- **PostgreSQL** must be installed and properly configured as the primary database.  \n- All inter-service communication related to **customers**, **orders**, and **campaign execution** happens through Kafka topics.  \n- Consumers are designed for **batch processing** and **asynchronous updates**, ensuring high throughput.  \n- Use `consumer.js` in the backend to listen and process messages from the above topics.  \n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecker-dev%2Fminicrm-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecker-dev%2Fminicrm-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecker-dev%2Fminicrm-backend/lists"}