cmp-aws-database/README.md

The package "cmp-aws-database" is for its database, which defines global tables. These tables are designed to be imported and used across multiple applications of "craft-my-plate."

# Craft My Plate Database Package

A comprehensive, environment-aware database package for the Craft My Plate application ecosystem. This package provides DynamoDB-based data access with automatic environment configuration.

## 🚀 Features

- **Environment-Aware Configuration**: Automatically adapts to development, staging, production, and test environments
- **Dynamic Table Naming**: Environment-specific table prefixes (dev-, staging-, test-)
- **Feature Flags**: Environment-specific feature toggles (parallel processing, caching, etc.)
- **TypeScript Support**: Full TypeScript definitions and type safety
- **AWS CDK Integration**: Infrastructure as Code for database tables
- **Comprehensive DAO Layer**: Generic data access objects with environment-specific optimizations

## 📦 Installation

```bash
npm install cmp-aws-database
```

## 🎯 Quick Start

### Basic Usage

```typescript
import { 
  envManager, 
  TABLE_NAMES, 
  UserModel, 
  userDAO 
} from 'cmp-aws-database';

// Check current environment
console.log('Environment:', envManager.getEnvironment());

// Use environment-aware table names
const userTableName = TABLE_NAMES.USER;

// Create and save a user
const user = new UserModel();
user.userId = 'user123';
user.email = 'test@example.com';

const savedUser = await userDAO.save(user, { userSub: 'auth-user-123' });
```

### Environment Configuration

The package automatically detects the environment based on `NODE_ENV` or `ENVIRONMENT` variables:

```bash
# Development
export NODE_ENV=development

# Staging  
export NODE_ENV=staging

# Production
export NODE_ENV=production

# Test
export NODE_ENV=test
```

## 🌍 Environment-Specific Behavior

### DEV Environment
- **Database**: Local DynamoDB (http://localhost:8000)
- **Table Prefix**: `dev-`
- **Features**: Sequential processing, no caching
- **Logging**: Debug level
- **Branch**: `environment/DEV`
- **NPM Tag**: `@dev`

### PRODDEBUG Environment
- **Database**: AWS DynamoDB
- **Table Prefix**: `proddebug-`
- **Features**: Parallel processing, caching enabled
- **Logging**: Info level
- **Branch**: `environment/PRODDEBUG`
- **NPM Tag**: `@proddebug`

### PROD Environment
- **Database**: AWS DynamoDB
- **Table Prefix**: None (empty)
- **Features**: Parallel processing, caching enabled
- **Logging**: Warn level
- **Branch**: `environment/PROD`
- **NPM Tag**: `@latest`

### Test Environment
- **Database**: Local DynamoDB (http://localhost:8000)
- **Table Prefix**: `test-`
- **Features**: Sequential processing, no caching
- **Logging**: Error level

## 📚 Available Models and DAOs

### Customer User Models
- `UserModel` / `userDAO`
- `OrderModel` / `orderDao`
- `CartModel` / `cartDAO`
- `WalletModel` / `walletDao`
- `PaymentModel` / `paymentDao`
- And many more...

### Internal User Models
- `InternalUserModel` / `internalUserDao`
- `ActivityLogsModel` / `activityLogsDao`
- `QuotationsModel` / `quotationsDao`

## 🔧 Advanced Usage

### Environment-Specific Features

```typescript
import { envManager } from 'cmp-aws-database';

const config = envManager.getConfig();

// Check if parallel processing is enabled
if (config.features.enableParallelProcessing) {
  await userDAO.parallelBatchGet(users);
} else {
  await userDAO.batchGet(users);
}

// Check if caching is enabled
if (config.features.enableCaching) {
  // Implement caching logic
}
```

### Custom Table Names

```typescript
import { TableNameManager } from 'cmp-aws-database';

const customTableName = TableNameManager.getTableName('MyCustomTable');
// Returns: dev-MyCustomTable, staging-MyCustomTable, or MyCustomTable
```

### Environment Override (Testing)

```typescript
import { envManager } from 'cmp-aws-database';

// Override environment for testing
envManager.setEnvironment('test');
```

## 🏗️ Infrastructure

### CDK Stack Deployment

```typescript
import { CustomerAppDbStack, InternalUserDbStack } from 'cmp-aws-database';

// Deploy customer app database
const customerStack = new CustomerAppDbStack(app, 'CustomerAppDbStack');

// Deploy internal user database  
const internalStack = new InternalUserDbStack(app, 'InternalUserDbStack');
```

### Available Tables

The package includes pre-configured tables for:
- User management
- Order processing
- Payment handling
- Inventory management
- Analytics and reporting
- And much more...

## 🔍 Debugging

### Environment Information

```typescript
import { envManager } from 'cmp-aws-database';

console.log('Current environment:', envManager.getEnvironment());
console.log('Database config:', envManager.getDatabaseConfig());
console.log('Features enabled:', envManager.getConfig().features);
```

### Table Name Resolution

```typescript
import { TABLE_NAMES, BASE_TABLE_NAMES } from 'cmp-aws-database';

console.log('Environment-aware table names:', TABLE_NAMES);
console.log('Base table names:', BASE_TABLE_NAMES);
```

## 📋 Migration Guide

### From Hardcoded Configuration

**Before:**
```typescript
const tableName = 'UserTable';
const client = new DynamoDB({ maxAttempts: 10 });
```

**After:**
```typescript
import { TABLE_NAMES, DatabaseFactory } from 'cmp-aws-database';

const tableName = TABLE_NAMES.USER;
const client = DatabaseFactory.getDynamoDBClient();
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## 📄 License

Apache-2.0

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/Surajpatel24-craftmyplate/craft-my-plate-database/issues)
- **Documentation**: [Package Documentation](https://github.com/Surajpatel24-craftmyplate/craft-my-plate-database#readme)

## 🌿 Branch-Based Publishing Strategy

### **Branch Structure**
```
master (main development)
├── environment/DEV (DEV environment)
├── environment/PRODDEBUG (PRODDEBUG environment)
└── environment/PROD (PROD environment)
```

### **Publishing Workflow**

#### **1. Create Environment Branches**
```bash
# Create all environment branches
npm run create-branches
```

#### **2. DEV Environment Publishing**
```bash
# Switch to DEV branch
git checkout environment/DEV

# Make changes and commit
git add .
git commit -m "Add new feature for DEV"
git push origin environment/DEV

# Publish to npm with @dev tag
npm run deploy:dev
```
**Result**: `cmp-aws-database@dev` (version: 1.1.107-dev.1)

#### **3. PRODDEBUG Environment Publishing**
```bash
# Switch to PRODDEBUG branch
git checkout environment/PRODDEBUG

# Promote changes from DEV
./scripts/git-workflow.sh promote DEV PRODDEBUG

# Publish to npm with @proddebug tag
npm run deploy:proddebug
```
**Result**: `cmp-aws-database@proddebug` (version: 1.1.107-proddebug.1)

#### **4. PROD Environment Publishing**
```bash
# Switch to PROD branch
git checkout environment/PROD

# Promote changes from PRODDEBUG
./scripts/git-workflow.sh promote PRODDEBUG PROD

# Publish to npm with @latest tag
npm run deploy:prod
```
**Result**: `cmp-aws-database@latest` (version: 1.1.107)

### **Installation Commands**
```bash
# Install DEV version
npm install cmp-aws-database@dev

# Install PRODDEBUG version
npm install cmp-aws-database@proddebug

# Install PROD version (latest)
npm install cmp-aws-database@latest
```

## 🔄 Version History

- **1.1.107**: Current version with environment-aware configuration
- **Previous versions**: Legacy hardcoded configuration

---

**Note**: This package uses branch-based publishing where each environment has its own branch and publishes with different NPM tags. The same package name is maintained across all environments while providing environment-specific configurations.