CLAUDE.md - Project Development Guidelines for BetCortex

Project Rules and Standards

This document contains strict guidelines that must be followed during the development of BetCortex. These rules ensure code quality, maintainability, and clean project structure.

🎯 Core Development Rules

1. Testing File Organization

STRICT RULE: All test files MUST be placed in designated

Test

folders within their respective directories.

✅ CORRECT Structure:
frontend/
├── src/
│   └── components/
│       └── BettingCard.tsx
└── Test/
    └── components/
        └── BettingCard.test.tsx

backend/
├── app/
│   └── services/
│       └── allocator.py
└── Test/
    └── services/
        └── test_allocator.py

❌ INCORRECT Structure:
frontend/
├── src/
│   └── components/
│       ├── BettingCard.tsx
│       └── BettingCard.test.tsx  # WRONG - test file mixed with source

2. File Creation Discipline

STRICT RULE: NO unnecessary files. Every file must serve a clear, immediate purpose.

❌ DO NOT CREATE:
- Placeholder files "for future use"
- Duplicate functionality files
- Test files for trivial functions
- Backup copies (use git for version control)
- Commented-out code files
- Example/sample files in production folders

✅ ONLY CREATE:
- Files with immediate implementation
- Files required for current functionality
- Essential configuration files
- Documentation that reflects actual implementation

3. Project Cleanliness Standards

STRICT RULE: Maintain a clean, organized project structure at all times.

File Naming Conventions:

Frontend (React/TypeScript):
- Components: PascalCase (BettingCard.tsx)
- Utilities: camelCase (calculateROI.ts)
- Hooks: camelCase with 'use' prefix (useLadderStrategy.ts)
- Types: PascalCase with .types.ts (Allocation.types.ts)

Backend (Python):
- Modules: snake_case (allocation_engine.py)
- Classes: PascalCase in code
- Tests: test_[module_name].py

Folder Structure Rules:

BetCortex/
├── frontend/
│   ├── src/
│   │   ├── app/              # Next.js app router pages
│   │   ├── components/       # Reusable components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── lib/             # Utilities and helpers
│   │   ├── store/           # State management
│   │   ├── styles/          # Global styles
│   │   └── types/           # TypeScript definitions
│   └── Test/                # All frontend tests
│
├── backend/
│   ├── app/
│   │   ├── api/             # API endpoints
│   │   ├── core/            # Core configurations
│   │   ├── models/          # Database models
│   │   ├── schemas/         # Pydantic schemas
│   │   └── services/        # Business logic
│   └── Test/                # All backend tests
│
├── docker/                  # Docker configurations
├── docs/                    # Documentation
└── scripts/                 # Utility scripts

4. Documentation Requirements

STRICT RULE: Create and maintain

DOCUMENTATION.md

file that reflects ONLY implemented features.

Documentation Structure:

# BetCortex Documentation

## Last Updated: [Date]
## Version: [Current Version]

## ✅ Implemented Features
### Feature Name
- Description of what has been implemented
- API endpoints created
- UI components built
- Database tables added
- Example usage

## 🚧 In Progress
### Feature Name
- What is currently being worked on
- Expected completion

## 📋 Not Yet Implemented
### Feature Name
- Planned but not started

Documentation Update Rules:

Update IMMEDIATELY after implementing a feature
Include code examples from ACTUAL implementation
Document API endpoints with real request/response
NO placeholder or "coming soon" documentation
Remove outdated information immediately

5. Git Commit and Push Strategy

STRICT RULE: Push to GitHub after EVERY major update.

What Constitutes a Major Update:

✅ PUSH REQUIRED:
- New feature implementation complete
- API endpoint creation
- Database schema changes
- UI component completion
- Bug fixes that affect functionality
- Configuration changes
- Dependency updates

❌ DON'T PUSH:
- Work in progress (unless in feature branch)
- Broken code
- Files with sensitive data (API keys, passwords)
- Large binary files
- Node_modules or virtual environment folders

Commit Message Format:

# Format: <type>: <subject>

feat: Add ladder exit strategy calculator
fix: Correct ROI calculation in allocator
docs: Update API documentation for /allocate endpoint
style: Format betting card component
refactor: Optimize database queries for performance
test: Add unit tests for allocation engine
chore: Update dependencies

Git Workflow:

# Before starting work
git pull origin main

# After major update
git add .
git commit -m "feat: Add [specific feature description]"
git push origin main

# For feature branches
git checkout -b feature/ladder-exit
# ... work ...
git add .
git commit -m "feat: Implement ladder exit calculations"
git push origin feature/ladder-exit
# Create PR for review

📁 Project-Specific Rules

Frontend Development Rules

Component Creation:
- One component per file
- Include TypeScript types
- NO inline styles (use Tailwind classes)
- Props interface must be defined
State Management:
- Use Zustand for global state
- Local state for component-specific data
- Avoid prop drilling
API Calls:
- All API calls through dedicated service files
- Proper error handling
- Loading states required

Backend Development Rules

API Endpoints:
- Clear RESTful naming
- Pydantic models for validation
- Comprehensive error responses
- Rate limiting on all public endpoints
Database Operations:
- Use SQLAlchemy ORM
- Raw SQL only when necessary
- All queries must be parameterized
- Connection pooling required
Service Layer:
- Business logic separated from routes
- Single responsibility principle
- Dependency injection where applicable

🚫 Prohibited Practices

NEVER commit directly to main without testing
NEVER create "temporary" files
NEVER leave console.log or print statements in production code
NEVER hardcode sensitive data
NEVER create files "just in case"
NEVER duplicate code (use utilities/shared components)
NEVER skip error handling
NEVER ignore TypeScript/Python type hints

✅ Required Practices

ALWAYS test before pushing
ALWAYS update documentation after implementation
ALWAYS follow the file structure
ALWAYS use meaningful variable/function names
ALWAYS handle loading and error states
ALWAYS validate user input
ALWAYS optimize for mobile first
ALWAYS consider performance implications

📊 Code Quality Standards

Frontend Quality Metrics:

TypeScript strict mode enabled
No any types (except absolutely necessary)
Lighthouse score > 90
Bundle size < 500KB initial load
Zero accessibility violations

Backend Quality Metrics:

Test coverage > 80%
API response time < 200ms
Zero critical security vulnerabilities
Proper error handling on all endpoints
Database queries optimized

🔄 Development Workflow

Start of Session:

git pull origin main
npm install / pip install -r requirements.txt
docker-compose up -d

During Development:
- Write code following all rules above
- Test functionality locally
- Update DOCUMENTATION.md
- Clean up any temporary files

End of Session:

# Run tests
npm test / pytest

# Check for issues
npm run lint / black . && isort .

# Commit and push
git add .
git commit -m "feat: [description]"
git push origin main

# Update documentation
# Edit DOCUMENTATION.md with new implementations
git add DOCUMENTATION.md
git commit -m "docs: Update documentation with [feature]"
git push origin main

📝 Documentation Template

Create

DOCUMENTATION.md

in the root directory:

# BetCortex Documentation

## Last Updated: [Current Date]
## Version: 0.1.0

## ✅ Implemented Features

### Authentication System
- JWT-based authentication with refresh tokens
- Endpoints:
  - POST /api/v1/auth/register
  - POST /api/v1/auth/login
  - POST /api/v1/auth/refresh
- Database tables: app_user, user_session
- Frontend: Login/Register components

### [Next Feature]
- Details...

## 🚧 In Progress

### Odds Upload System
- Expected completion: [Date]
- Current status: LLM integration 60% complete

## 📋 Not Yet Implemented

### Ladder Exit Strategy
### Payment Integration
### Performance Tracking

🎯 Quick Reference Checklist

Before ANY commit, verify:

🚨 Important Commands

# Clean up before pushing
find . -name "*.pyc" -delete
find . -name "__pycache__" -delete
find . -name ".DS_Store" -delete

# Check for large files
find . -type f -size +1M

# Run all tests
npm test && cd ../backend && pytest

# Format code
npm run format && black . && isort .

# Build check
npm run build && docker-compose build

Remember: These rules exist to maintain a professional, clean, and efficient codebase. Following them strictly will result in a maintainable and scalable application.

GitHub Repository: https://github.com/rshinytools/BetCortex

This document is mandatory reading before any development work. Non-compliance will require code refactoring.

CLAUDE.md - Project Development Guidelines for BetCortex

Project Rules and Standards

This document contains strict guidelines that must be followed during the development of BetCortex. These rules ensure code quality, maintainability, and clean project structure.

🎯 Core Development Rules

1. Testing File Organization

STRICT RULE: All test files MUST be placed in designated

Test

folders within their respective directories.

✅ CORRECT Structure:
frontend/
├── src/
│   └── components/
│       └── BettingCard.tsx
└── Test/
    └── components/
        └── BettingCard.test.tsx

backend/
├── app/
│   └── services/
│       └── allocator.py
└── Test/
    └── services/
        └── test_allocator.py

❌ INCORRECT Structure:
frontend/
├── src/
│   └── components/
│       ├── BettingCard.tsx
│       └── BettingCard.test.tsx  # WRONG - test file mixed with source

2. File Creation Discipline

STRICT RULE: NO unnecessary files. Every file must serve a clear, immediate purpose.

❌ DO NOT CREATE:
- Placeholder files "for future use"
- Duplicate functionality files
- Test files for trivial functions
- Backup copies (use git for version control)
- Commented-out code files
- Example/sample files in production folders

✅ ONLY CREATE:
- Files with immediate implementation
- Files required for current functionality
- Essential configuration files
- Documentation that reflects actual implementation

3. Project Cleanliness Standards

STRICT RULE: Maintain a clean, organized project structure at all times.

File Naming Conventions:

Frontend (React/TypeScript):
- Components: PascalCase (BettingCard.tsx)
- Utilities: camelCase (calculateROI.ts)
- Hooks: camelCase with 'use' prefix (useLadderStrategy.ts)
- Types: PascalCase with .types.ts (Allocation.types.ts)

Backend (Python):
- Modules: snake_case (allocation_engine.py)
- Classes: PascalCase in code
- Tests: test_[module_name].py

Folder Structure Rules:

BetCortex/
├── frontend/
│   ├── src/
│   │   ├── app/              # Next.js app router pages
│   │   ├── components/       # Reusable components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── lib/             # Utilities and helpers
│   │   ├── store/           # State management
│   │   ├── styles/          # Global styles
│   │   └── types/           # TypeScript definitions
│   └── Test/                # All frontend tests
│
├── backend/
│   ├── app/
│   │   ├── api/             # API endpoints
│   │   ├── core/            # Core configurations
│   │   ├── models/          # Database models
│   │   ├── schemas/         # Pydantic schemas
│   │   └── services/        # Business logic
│   └── Test/                # All backend tests
│
├── docker/                  # Docker configurations
├── docs/                    # Documentation
└── scripts/                 # Utility scripts

4. Documentation Requirements

STRICT RULE: Create and maintain

DOCUMENTATION.md

file that reflects ONLY implemented features.

Documentation Structure:

# BetCortex Documentation

## Last Updated: [Date]
## Version: [Current Version]

## ✅ Implemented Features
### Feature Name
- Description of what has been implemented
- API endpoints created
- UI components built
- Database tables added
- Example usage

## 🚧 In Progress
### Feature Name
- What is currently being worked on
- Expected completion

## 📋 Not Yet Implemented
### Feature Name
- Planned but not started

Documentation Update Rules:

Update IMMEDIATELY after implementing a feature
Include code examples from ACTUAL implementation
Document API endpoints with real request/response
NO placeholder or "coming soon" documentation
Remove outdated information immediately

5. Git Commit and Push Strategy

STRICT RULE: Push to GitHub after EVERY major update.

What Constitutes a Major Update:

✅ PUSH REQUIRED:
- New feature implementation complete
- API endpoint creation
- Database schema changes
- UI component completion
- Bug fixes that affect functionality
- Configuration changes
- Dependency updates

❌ DON'T PUSH:
- Work in progress (unless in feature branch)
- Broken code
- Files with sensitive data (API keys, passwords)
- Large binary files
- Node_modules or virtual environment folders

Commit Message Format:

# Format: <type>: <subject>

feat: Add ladder exit strategy calculator
fix: Correct ROI calculation in allocator
docs: Update API documentation for /allocate endpoint
style: Format betting card component
refactor: Optimize database queries for performance
test: Add unit tests for allocation engine
chore: Update dependencies

Git Workflow:

# Before starting work
git pull origin main

# After major update
git add .
git commit -m "feat: Add [specific feature description]"
git push origin main

# For feature branches
git checkout -b feature/ladder-exit
# ... work ...
git add .
git commit -m "feat: Implement ladder exit calculations"
git push origin feature/ladder-exit
# Create PR for review

📁 Project-Specific Rules

Frontend Development Rules

Component Creation:
- One component per file
- Include TypeScript types
- NO inline styles (use Tailwind classes)
- Props interface must be defined
State Management:
- Use Zustand for global state
- Local state for component-specific data
- Avoid prop drilling
API Calls:
- All API calls through dedicated service files
- Proper error handling
- Loading states required

Backend Development Rules

API Endpoints:
- Clear RESTful naming
- Pydantic models for validation
- Comprehensive error responses
- Rate limiting on all public endpoints
Database Operations:
- Use SQLAlchemy ORM
- Raw SQL only when necessary
- All queries must be parameterized
- Connection pooling required
Service Layer:
- Business logic separated from routes
- Single responsibility principle
- Dependency injection where applicable

🚫 Prohibited Practices

NEVER commit directly to main without testing
NEVER create "temporary" files
NEVER leave console.log or print statements in production code
NEVER hardcode sensitive data
NEVER create files "just in case"
NEVER duplicate code (use utilities/shared components)
NEVER skip error handling
NEVER ignore TypeScript/Python type hints

✅ Required Practices

ALWAYS test before pushing
ALWAYS update documentation after implementation
ALWAYS follow the file structure
ALWAYS use meaningful variable/function names
ALWAYS handle loading and error states
ALWAYS validate user input
ALWAYS optimize for mobile first
ALWAYS consider performance implications

📊 Code Quality Standards

Frontend Quality Metrics:

TypeScript strict mode enabled
No any types (except absolutely necessary)
Lighthouse score > 90
Bundle size < 500KB initial load
Zero accessibility violations

Backend Quality Metrics:

Test coverage > 80%
API response time < 200ms
Zero critical security vulnerabilities
Proper error handling on all endpoints
Database queries optimized

🔄 Development Workflow

Start of Session:

git pull origin main
npm install / pip install -r requirements.txt
docker-compose up -d

During Development:
- Write code following all rules above
- Test functionality locally
- Update DOCUMENTATION.md
- Clean up any temporary files

End of Session:

# Run tests
npm test / pytest

# Check for issues
npm run lint / black . && isort .

# Commit and push
git add .
git commit -m "feat: [description]"
git push origin main

# Update documentation
# Edit DOCUMENTATION.md with new implementations
git add DOCUMENTATION.md
git commit -m "docs: Update documentation with [feature]"
git push origin main

📝 Documentation Template

Create

DOCUMENTATION.md

in the root directory:

# BetCortex Documentation

## Last Updated: [Current Date]
## Version: 0.1.0

## ✅ Implemented Features

### Authentication System
- JWT-based authentication with refresh tokens
- Endpoints:
  - POST /api/v1/auth/register
  - POST /api/v1/auth/login
  - POST /api/v1/auth/refresh
- Database tables: app_user, user_session
- Frontend: Login/Register components

### [Next Feature]
- Details...

## 🚧 In Progress

### Odds Upload System
- Expected completion: [Date]
- Current status: LLM integration 60% complete

## 📋 Not Yet Implemented

### Ladder Exit Strategy
### Payment Integration
### Performance Tracking

🎯 Quick Reference Checklist

Before ANY commit, verify:

🚨 Important Commands

# Clean up before pushing
find . -name "*.pyc" -delete
find . -name "__pycache__" -delete
find . -name ".DS_Store" -delete

# Check for large files
find . -type f -size +1M

# Run all tests
npm test && cd ../backend && pytest

# Format code
npm run format && black . && isort .

# Build check
npm run build && docker-compose build

Remember: These rules exist to maintain a professional, clean, and efficient codebase. Following them strictly will result in a maintainable and scalable application.

GitHub Repository: https://github.com/rshinytools/BetCortex

This document is mandatory reading before any development work. Non-compliance will require code refactoring.

CLAUDE.md - Project Development Guidelines for BetCortex

Related Skills

Nano Banana Pro

Markdown Converter

1password