126 lines
4.6 KiB
Markdown
126 lines
4.6 KiB
Markdown
# 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)
|