roadmap/schemas/README.md

# Split Schema Structure

This directory contains the split version of the agricultural platform's Prisma schema, organized by domain for better maintainability and team collaboration.

## Directory Structure

```
schemas/
├── README.md                # This file
├── base.prisma             # Generator, datasource, and shared enums
├── user.prisma             # User management (User, Farmer, Buyer, Administrator)
├── reference.prisma        # Reference data (Country, Currency, Religion, EducationLevel)
├── farm.prisma             # Farm management (Farm, Plot, SoilTest, FarmAttachment)
├── product.prisma          # Product system (Product, ProductVariant, modifiers)
├── procurement.prisma      # Trading (Procurement, Contract, Harvest)
├── season.prisma           # Seasonal planning (Season, PlotSeason, analytics)
├── operations.prisma       # Operations (Input, Labor, Equipment, Assets)
├── financial.prisma        # Financial records and transactions
├── communication.prisma    # Notifications and messaging
├── weather.prisma          # Weather data and forecasts
├── training.prisma         # Training and certification
├── market.prisma           # Market intelligence and pricing
├── knowledge.prisma        # Articles and knowledge base
├── attachments.prisma      # File and attachment management
└── pest-disease.prisma     # Pest, disease, and review management
```

## Benefits of Split Schema

### 1. **Better Organization**
- Logical grouping by business domain
- Easier to find specific models
- Reduced cognitive load when working on specific features
- Clear separation of concerns

### 2. **Team Collaboration**
- Multiple developers can work on different schema files simultaneously
- Reduced merge conflicts
- Clear ownership boundaries
- Focused code reviews

### 3. **Maintainability**
- Easier to understand and modify specific domains
- Better debugging and troubleshooting
- Cleaner dependency management
- Improved documentation per domain

### 4. **Performance Benefits**
- Faster schema compilation for individual domains
- Easier to identify bottlenecks
- Better indexing strategy per domain
- Optimized queries per business area

## How to Use Split Schema

### Option 1: Replace Original Schema
1. **Backup original schema.prisma**:
   ```bash
   mv schema.prisma schema.prisma.backup
   ```

2. **Use split schema directory**:
   ```bash
   # Prisma will automatically read all .prisma files in the directory
   npx prisma generate
   npx prisma migrate dev
   ```

### Option 2: Parallel Development
Keep both structures and choose based on your needs:
- Use original `schema.prisma` for production
- Use `schemas/` directory for development and feature work
- Gradually migrate teams to split structure

## Domain Responsibilities

### **Core Domains**
- **user.prisma**: Authentication, user profiles, role management
- **reference.prisma**: Master data (countries, currencies, education levels)
- **farm.prisma**: Farm infrastructure, plots, soil management

### **Business Domains**
- **product.prisma**: Product catalog, variants, quality modifiers
- **procurement.prisma**: Trading, contracts, harvest management
- **season.prisma**: Agricultural cycles, seasonal planning
- **operations.prisma**: Daily operations, labor, equipment

### **Support Domains**
- **financial.prisma**: Financial tracking, transactions
- **communication.prisma**: Notifications, messaging
- **weather.prisma**: Climate data, forecasts
- **training.prisma**: Education, certifications

### **Analytics Domains**
- **market.prisma**: Market intelligence, pricing
- **knowledge.prisma**: Content management
- **attachments.prisma**: File management
- **pest-disease.prisma**: Agricultural health tracking

## File Size Comparison

| Structure | File Count | Lines per File | Total Lines |
|-----------|------------|----------------|-------------|
| Original  | 1 file     | ~1,800 lines   | 1,800       |
| Split     | 15 files   | ~120-300 lines| 1,800       |

## Cross-Domain Relationships

The split maintains all relationships between domains:

```prisma
// farmer.prisma references farm.prisma
model Farmer {
  farms Farm[] // → farm.prisma
}

// farm.prisma references farmer.prisma  
model Farm {
  farmer Farmer @relation(...) // → user.prisma
}
```

## Migration Strategy

### Phase 1: Parallel Structure
- Keep original schema.prisma
- Create split structure alongside
- Use for new feature development

### Phase 2: Team Adoption
- Train teams on domain boundaries
- Establish ownership per domain
- Use split structure for reviews

### Phase 3: Full Migration
- Move production to split structure
- Archive original schema.prisma
- Update CI/CD pipelines

## Best Practices

### 1. **Domain Boundaries**
- Keep related models together
- Minimize cross-domain dependencies
- Use clear naming conventions

### 2. **Shared Elements**
- Keep shared enums in base.prisma
- Document cross-domain relationships
- Maintain consistent data types

### 3. **Team Workflow**
- Assign domain ownership
- Review changes by domain
- Coordinate cross-domain changes

### 4. **Development**
- Test schema compilation regularly
- Validate relationships across files
- Monitor performance impact

## Troubleshooting

### Common Issues

1. **Duplicate Models/Enums**:
   - Ensure original schema.prisma is not in the same directory
   - Check for naming conflicts across files

2. **Missing Relations**:
   - Verify cross-file relationships are properly defined
   - Check import paths and model references

3. **Compilation Errors**:
   - Run `npx prisma validate` to check schema integrity
   - Verify all referenced models exist across files

### Validation Commands

```bash
# Validate entire schema
npx prisma validate

# Generate client to test compilation
npx prisma generate

# Check database sync
npx prisma migrate dev --create-only
```

## Future Enhancements

### Potential Improvements
1. **Microservice Extraction**: Easier to identify service boundaries
2. **Database Sharding**: Clear data partitioning strategies
3. **Team Scaling**: Better support for large development teams
4. **Domain-Driven Design**: Enhanced DDD implementation

### Monitoring
- Track file modification patterns
- Monitor domain interaction frequency
- Identify optimization opportunities

## Support

For questions about the split schema structure:
1. Check this README for common issues
2. Review domain documentation in each file
3. Validate schema compilation with Prisma CLI
4. Contact the database team for complex migrations

---

**Note**: This split structure maintains full compatibility with the original schema.prisma. All relationships, constraints, and data types remain identical.