Shared Database Package

This package contains shared TypeORM entities, migrations, enums, and database configuration for use across multiple backend services in the AI Calling platform.

Installation

npm install
npm run build

Usage

In Migration Owner Backend

The backend service responsible for running database migrations should use getTypeOrmConfig:

import { getTypeOrmConfig, AllEntities } from 'ai-calling-shared-database';

const dataSource = new DataSource({
  ...getTypeOrmConfig(),
  entities: AllEntities,
});

In Consumer Backends

Other backend services that share the database but don't run migrations should use getSharedDbConfig:

import { getSharedDbConfig, AllEntities } from 'ai-calling-shared-database';

const dataSource = new DataSource({
  ...getSharedDbConfig(),
  entities: AllEntities,
});

Importing Individual Entities

import { 
  User, 
  Project, 
  Campaign, 
  Call, 
  Contact, 
  Phone, 
  ServiceProvider, 
  CallResult 
} from 'ai-calling-shared-database';

Importing Enums

import { 
  UserRole, 
  PhoneStatus, 
  CampaignStatus, 
  ContactStatus, 
  CallStatus, 
  ResultType 
} from 'ai-calling-shared-database';

Entity Structure

Entity Relationship Diagram

User
 ├── Project (user_id)
 │    ├── Campaign (project_id)
 │    │    ├── Contact (campaign_id)
 │    │    └── Call (campaign_id)
 │    └── Phone (project_id, optional)
 │
 ├── Campaign (user_id)
 │
 └── Phone (user_id)

ServiceProvider
 ├── Project (service_id)
 ├── Phone (service_id)
 └── Call (service_id)

Call
 ├── CallResult (call_id)
 └── References: Campaign, User, Project, Phone, Contact, ServiceProvider

Entities

User (users)

Represents system users with authentication and authorization.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | email | string | Unique email address | | password | string | Hashed password | | firstName | string | User's first name | | lastName | string | User's last name | | name | string? | Optional display name | | role | UserRole | User role (admin, user) | | permissions | string[] | Array of permission strings | | settings | jsonb? | User settings (JSON) | | is_active | boolean | Active status (default: true) | | createdAt | Date | Creation timestamp | | updatedAt | Date | Last update timestamp | | created_at | Date | Alternative creation timestamp |

Relationships:

• One-to-Many: Project, Campaign, Phone

Project (projects)

Represents AI calling projects with configuration and prompts.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | user_id | uuid | Foreign key to users | | service_id | uuid | Foreign key to service_providers | | name | string | Project name | | heading | string? | Project heading | | description | string? | Project description | | system_prompt | text? | AI system prompt for calls | | is_active | boolean | Active status (default: true) | | created_at | Date | Creation timestamp |

Relationships:

• Many-to-One: User, ServiceProvider
• One-to-Many: Campaign, Phone (optional)

Campaign (campaigns)

Represents calling campaigns that organize contacts and calls.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | user_id | uuid | Foreign key to users | | project_id | uuid | Foreign key to projects | | phone_id | uuid | Foreign key to phones | | name | string | Campaign name | | description | string? | Campaign description | | status | CampaignStatus | Campaign status (draft, uploading, ready, running, paused, completed) | | stats | jsonb? | Campaign statistics (JSON) | | is_active | boolean | Active status (default: true) | | created_at | Date | Creation timestamp |

Relationships:

• Many-to-One: User, Project, Phone
• One-to-Many: Contact, Call

Contact (contacts)

Represents contacts to be called in a campaign.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | campaign_id | uuid | Foreign key to campaigns | | phone_number | string | Contact phone number | | name | string? | Contact name | | status | ContactStatus | Contact status (pending, calling, qualified, not_interested, callback, failed) | | error_reason | string? | Error reason if failed | | is_active | boolean | Active status (default: true) | | created_at | Date | Creation timestamp |

Relationships:

• Many-to-One: Campaign
• One-to-Many: Call

Phone (phones)

Represents phone numbers used for making calls.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | user_id | uuid | Foreign key to users | | project_id | uuid? | Foreign key to projects (optional) | | service_id | uuid | Foreign key to service_providers | | phone_number | string | Phone number | | provider_phone_id | string? | Provider's phone ID | | status | PhoneStatus | Phone status (active, inactive) | | is_occupied | boolean | Whether phone is currently in use (default: false) | | is_active | boolean | Active status (default: true) | | created_at | Date | Creation timestamp |

Relationships:

• Many-to-One: User, Project (optional), ServiceProvider
• One-to-Many: Campaign, Call

Call (calls)

Represents individual call records.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | campaign_id | uuid | Foreign key to campaigns | | user_id | uuid | Foreign key to users | | project_id | uuid | Foreign key to projects | | phone_id | uuid | Foreign key to phones | | contact_id | uuid | Foreign key to contacts | | service_id | uuid | Foreign key to service_providers | | provider_call_id | string? | Provider's call ID | | status | CallStatus | Call status (initiated, answered, completed, failed) | | started_at | timestamp? | Call start time | | ended_at | timestamp? | Call end time | | is_active | boolean | Active status (default: true) | | created_at | Date | Creation timestamp |

Relationships:

• Many-to-One: Campaign, User, Project, Phone, Contact, ServiceProvider
• One-to-Many: CallResult

CallResult (call_results)

Stores various types of results and data from calls.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | call_id | uuid | Foreign key to calls | | result_type | ResultType | Type of result (provider_raw, transcript, ai_qualification, summary, error) | | payload | jsonb | Result data (JSON) | | is_active | boolean | Active status (default: true) | | created_at | Date | Creation timestamp |

Relationships:

• Many-to-One: Call

ServiceProvider (service_providers)

Represents external service providers for phone services.

| Field | Type | Description | |-------|------|-------------| | id | uuid | Primary key (auto-generated) | | name | string | Provider name | | api_key | string | Provider API key | | is_active | boolean | Active status (default: true) |

Relationships:

• One-to-Many: Project, Phone, Call

Enums

UserRole

• ADMIN - Administrator role
• USER - Standard user role

PhoneStatus

• ACTIVE - Phone is active
• INACTIVE - Phone is inactive

CampaignStatus

• DRAFT - Campaign is being created
• UPLOADING - Contacts are being uploaded
• READY - Campaign is ready to run
• RUNNING - Campaign is actively running
• PAUSED - Campaign is paused
• COMPLETED - Campaign has finished

ContactStatus

• PENDING - Contact is waiting to be called
• CALLING - Contact is currently being called
• QUALIFIED - Contact has been qualified
• NOT_INTERESTED - Contact is not interested
• CALLBACK - Contact requested a callback
• FAILED - Call to contact failed

CallStatus

• INITIATED - Call has been initiated
• ANSWERED - Call was answered
• COMPLETED - Call completed successfully
• FAILED - Call failed

ResultType

• PROVIDER_RAW - Raw data from provider
• TRANSCRIPT - Call transcript
• AI_QUALIFICATION - AI qualification result
• SUMMARY - Call summary
• ERROR - Error result

Package Structure

packages/shared-database/
├── src/
│   ├── entities/          # All TypeORM entities
│   │   ├── user.entity.ts
│   │   ├── project.entity.ts
│   │   ├── campaign.entity.ts
│   │   ├── call.entity.ts
│   │   ├── contact.entity.ts
│   │   ├── phone.entity.ts
│   │   ├── service-provider.entity.ts
│   │   └── call-result.entity.ts
│   ├── migrations/        # Database migrations
│   │   └── 1768928694011-init-schema.ts
│   ├── config/            # TypeORM configuration
│   │   └── typeorm.config.ts
│   ├── common/            # Shared enums and types
│   │   └── enums.ts
│   └── index.ts           # Main export file
├── dist/                  # Compiled output (generated)
├── package.json
└── tsconfig.json

Building

npm run build

This compiles TypeScript to JavaScript in the dist/ folder.

Development

For watch mode during development:

npm run watch

Publishing

If using a private npm registry:

npm version patch
npm publish

Or for local development, use npm link or file:../packages/shared-database in package.json.