BetCortex Development Standards
Enforce strict development guidelines for the BetCortex sports betting platform, ensuring clean project structure, proper test organization, and quality code practices.
Core Development Rules
1. Test File Organization
**CRITICAL:** All test files MUST be in designated `Test/` folders, never mixed with source code.
**Correct structure:**
Frontend: `frontend/Test/components/BettingCard.test.tsx`Backend: `backend/Test/services/test_allocator.py`**Check before creating test files:**
Verify `Test/` folder exists in the module directoryCreate `Test/` folder if missingPlace ALL test files inside `Test/` folder only2. File Creation Discipline
**NEVER create unnecessary files:**
No placeholder files "for future use"No duplicate functionalityNo backup copies (use git)No commented-out code filesNo example/sample files in production folders**Only create files with immediate, clear purpose for current implementation.**
3. Project Structure Standards
**Frontend (Next.js/React/TypeScript):**
```
frontend/
├── src/
│ ├── app/ # Next.js app router pages
│ ├── components/ # Reusable components (PascalCase.tsx)
│ ├── hooks/ # Custom hooks (useName.ts)
│ ├── lib/ # Utilities (camelCase.ts)
│ ├── store/ # State management (Zustand)
│ ├── styles/ # Global styles
│ └── types/ # TypeScript definitions (Name.types.ts)
└── Test/ # All frontend tests
```
**Backend (FastAPI/Python):**
```
backend/
├── app/
│ ├── api/ # API endpoints
│ ├── core/ # Core configurations
│ ├── models/ # Database models (SQLAlchemy)
│ ├── schemas/ # Pydantic schemas
│ └── services/ # Business logic (snake_case.py)
└── Test/ # All backend tests (test_*.py)
```
4. Documentation Requirements
**Maintain `DOCUMENTATION.md` reflecting ONLY implemented features:**
```markdown
BetCortex Documentation
Last Updated: [Date]
Version: [Current Version]
✅ Implemented Features
Feature Name
Description of implementationAPI endpoints createdUI components builtDatabase tables addedExample usage with actual code🚧 In Progress
Feature Name
Current work statusExpected completion📋 Not Yet Implemented
Feature Name
Planned but not started```
**Update documentation IMMEDIATELY after implementing features. Include:**
Real API endpoints with request/response examplesActual code snippets from implementationDatabase schema changesNO placeholder or "coming soon" content5. Git Workflow
**Push after EVERY major update:**
New feature completeAPI endpoint createdDatabase schema changeUI component completionBug fix affecting functionalityConfiguration or dependency updates**Commit message format:**
```
<type>: <subject>
Types:
feat: New featurefix: Bug fixdocs: Documentationstyle: Formattingrefactor: Code restructuringtest: Test additionschore: Maintenance```
**Standard workflow:**
```bash
Start session
git pull origin main
After major update
git add .
git commit -m "feat: Add [specific feature]"
git push origin main
Feature branch workflow
git checkout -b feature/name
... work ...
git commit -m "feat: Implement [feature]"
git push origin feature/name
Create PR
```
Component-Specific Rules
Frontend Development
One component per fileTypeScript strict mode (no `any` types)Props interface defined for all componentsUse Tailwind CSS classes (no inline styles)Zustand for global state, local state for component-specificAPI calls through dedicated service filesProper error and loading statesBackend Development
RESTful API naming conventionsPydantic models for all request/response validationSQLAlchemy ORM for database operationsParameterized queries only (security)Business logic in service layer (separated from routes)Rate limiting on public endpointsComprehensive error responsesCode Quality Standards
**Frontend metrics:**
TypeScript strict mode enabledLighthouse score > 90Bundle size < 500KB initial loadZero accessibility violations**Backend metrics:**
Test coverage > 80%API response time < 200msZero critical security vulnerabilitiesOptimized database queriesProhibited Practices
**NEVER:**
Commit untested code to mainCreate "temporary" filesLeave `console.log` or `print` in productionHardcode sensitive dataCreate files "just in case"Duplicate code (use utilities/shared components)Skip error handlingIgnore type hintsPre-Commit Checklist
Before ANY commit, verify:
[ ] No test files outside `Test/` folders[ ] No unnecessary files created[ ] `DOCUMENTATION.md` updated with new features[ ] Code tested and working locally[ ] No sensitive data exposed[ ] Follows naming conventions[ ] Error handling implemented[ ] TypeScript/Python type hints includedCleanup Commands
```bash
Remove build artifacts
find . -name "*.pyc" -delete
find . -name "__pycache__" -delete
find . -name ".DS_Store" -delete
Check for large files
find . -type f -size +1M
Run tests
npm test && cd ../backend && pytest
Format code
npm run format && black . && isort .
Build verification
npm run build && docker-compose build
```
Session Workflow
**Start of session:**
```bash
git pull origin main
npm install # or pip install -r requirements.txt
docker-compose up -d
```
**During development:**
Follow all rules aboveTest functionality locallyUpdate `DOCUMENTATION.md` immediatelyClean up temporary files**End of session:**
```bash
Run tests
npm test # or pytest
Check code quality
npm run lint # or black . && isort .
Commit and push
git add .
git commit -m "feat: [description]"
git push origin main
Update docs if changed
git add DOCUMENTATION.md
git commit -m "docs: Update with [feature]"
git push origin main
```
Important Notes
**Repository:** https://github.com/rshinytools/BetCortex**Tech stack:** Next.js 14, React, TypeScript, FastAPI, Python, SQLAlchemy, PostgreSQL**Mobile-first design:** Optimize for mobile before desktop**Security:** Never commit API keys, passwords, or sensitive credentials**Dependencies:** Document all package additions in commit messagesThese rules maintain a professional, clean, and efficient codebase. Non-compliance requires immediate refactoring.