euchre_camp/docs/FILE_ORGANIZATION.md

File Organization

This document describes the organization of files in the EuchreCamp project.

Root Directory

Essential Files (Keep in Root)

• README.md - Main project documentation
• AGENTS.md - AI agent guide
• CHANGELOG.md - Version changelog
• package.json - Node.js dependencies and scripts
• package-lock.json - Dependency lock file
• tsconfig.json - TypeScript configuration
• next.config.js - Next.js configuration
• .gitignore - Git ignore file
• Dockerfile - Docker build configuration
• justfile - Development task automation

Configuration Files (Keep in Root)

• .eslintrc.json - ESLint configuration
• postcss.config.mjs - PostCSS configuration
• playwright.config.ts - Playwright test configuration
• vitest.config.mts - Vitest configuration
• vitest.setup.ts - Vitest setup
• .dockerignore - Docker ignore file
• mise.toml - Mise version manager config

Docker Files (Keep in Root)

• docker-compose.yml - Main Docker Compose
• docker-compose.dev.yml - Development Docker Compose
• docker-compose.override.yml - Override for dev
• docker-compose.casaos.yml - CasaOS specific

Environment Files (Keep in Root, Gitignored)

• .env - Environment variables
• .env.development - Development environment

Organized Directories

.gitea/ - Gitea Actions Workflows

• workflows/pr.yml - Pull request workflow (unit + acceptance tests)
• workflows/test.yml - Test workflow (unit tests on branch pushes)
• workflows/release.yml - Release workflow (version bump + Docker build)
• WORKFLOW_ARCHITECTURE.md - Workflow architecture documentation

docs/ - Documentation

• deployment/ - Deployment documentation
  • CASAOS_DEPLOYMENT.md - CasaOS deployment guide
  • DOCKER.md - Docker deployment instructions
• TODO.md - Project TODO list (in docs root for visibility)
• USER_STORIES.md - User stories organized by epic
• Other documentation files (design, implementation, testing, etc.)

scripts/ - Utility Scripts

• python/ - Python scripts (legacy/old functionality)
  • generate_games.py - Generate sample games
  • update_partnership_stats.py - Update partnership stats
  • update_player_stats.py - Update player stats
• bump-version.js - Version bumping script
• build-and-push-docker.js - Docker build and push script
• switch-database.js - Database provider switching
• create-admin-via-api.js - Admin user creation via API
• create-admin-better-auth.js - Admin user creation via database
• list-users.js - List all users
• update-admin-password.js - Update admin password
• seed.js - Database seeding
• And other Node.js scripts...

src/ - Source Code

• app/ - Next.js app directory
  • api/ - API routes
  • auth/ - Authentication pages
  • admin/ - Admin pages
  • players/ - Player pages
  • rankings/ - Rankings page
  • components/ - Shared components
• lib/ - Utilities and configuration
  • auth.ts - Better Auth configuration
  • prisma.ts - Prisma client (supports SQLite and PostgreSQL)
  • permissions.ts - Authorization functions
  • elo-utils.ts - Elo calculation utilities
• __tests__/ - Vitest and Playwright tests
  • unit/ - Unit tests
  • e2e/ - End-to-end acceptance tests

prisma/ - Database

• schema.prisma - Prisma schema
• migrations/ - Database migrations
• dev.db - SQLite development database (if using SQLite)

public/ - Static Assets

• Images, fonts, and other static files

playwright/ - Playwright Test Data

• Authentication state files

Generated Directories (Gitignored)

• .next/ - Next.js build output
• node_modules/ - Node.js dependencies
• playwright-report/ - Playwright test reports
• test-results/ - Test results

File Organization Principles

1. Keep standard files in root: package.json, tsconfig.json, etc.
2. Organize by function: Group related files in directories
3. Separate generated from source: Keep build outputs and dependencies separate
4. Document organization: Use this file to explain structure
5. Follow conventions: Use standard naming and organization patterns

CI/CD File Organization

Workflows

• .gitea/workflows/pr.yml - Pull request validation
• .gitea/workflows/test.yml - Branch testing
• .gitea/workflows/release.yml - Main branch release

Database Strategy

• CI/Testing: SQLite (fast, no server)
• Production: PostgreSQL (production-like)

Testing

• Unit tests: npm run test:run
• Acceptance tests (SQLite): DATABASE_PROVIDER=sqlite npm run test:acceptance
• Acceptance tests (PostgreSQL): npm run test:acceptance (with Docker)