From 0e1046fcb5f9a1c83de18d9f60f23d75dfb3f2db Mon Sep 17 00:00:00 2001
From: David Gwilliam <dhgwilliam@gmail.com>
Date: Tue, 31 Mar 2026 21:49:07 -0700
Subject: [PATCH] docs: add FILE_ORGANIZATION.md to document project structure

---
 docs/FILE_ORGANIZATION.md | 125 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 docs/FILE_ORGANIZATION.md

diff --git a/docs/FILE_ORGANIZATION.md b/docs/FILE_ORGANIZATION.md
new file mode 100644
index 0000000..179e3fe
--- /dev/null
+++ b/docs/FILE_ORGANIZATION.md
@@ -0,0 +1,125 @@
+# 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)