# 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)