diff --git a/README.md b/README.md index 840b020..d6e17fe 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,21 @@ When constructing the file remember that the encoded form can not contain a trai - [Product and Sprint Backlogs](https://github.com/orgs/OHTU-German-learning-website/projects/4) -- Migrations: check [the migration README](data/README.md) +- Migrations: check [the migration README](gradesa/data/DATABASE_MIGRATIONS.md) + +## Appendix: Project Documentation + +Organized documentation files throughout the repository: + +- **[gradesa/NEXTJS_APP_GUIDE.md](gradesa/NEXTJS_APP_GUIDE.md)** – Next.js development server setup, testing with Vitest, and coverage UI +- **[gradesa/GLOBAL_MIDDLEWARE.md](gradesa/GLOBAL_MIDDLEWARE.md)** – Global Next.js middleware for route protection and auth redirects +- **[gradesa/data/DATABASE_MIGRATIONS.md](gradesa/data/DATABASE_MIGRATIONS.md)** – Database migration workflow using pgmigrate +- **[gradesa/playwright/e2e/E2E_TESTS.md](gradesa/playwright/e2e/E2E_TESTS.md)** – End-to-end testing documentation +- **[gradesa/src/SOURCE_OVERVIEW.md](gradesa/src/SOURCE_OVERVIEW.md)** – High-level source code organization, patterns, and conventions +- **[gradesa/src/backend/middleware/BACKEND_MIDDLEWARE.md](gradesa/src/backend/middleware/BACKEND_MIDDLEWARE.md)** – Backend middleware wrappers (withAuth, withInputValidation) +- **[gradesa/src/context/APP_CONTEXTS.md](gradesa/src/context/APP_CONTEXTS.md)** – React context providers (user auth, glossary) +- **[gradesa/src/shared/hooks/DATA_FETCHING_HOOKS.md](gradesa/src/shared/hooks/DATA_FETCHING_HOOKS.md)** – Custom data fetching hooks (useQuery, useRequest) +- **[gradesa/src/components/ui/layout/LAYOUT_COMPONENTS.md](gradesa/src/components/ui/layout/LAYOUT_COMPONENTS.md)** – Layout component system (Container, Row, Column) ## Definition of Done diff --git a/gradesa/MIDDLEWARE.md b/gradesa/GLOBAL_MIDDLEWARE.md similarity index 100% rename from gradesa/MIDDLEWARE.md rename to gradesa/GLOBAL_MIDDLEWARE.md diff --git a/gradesa/README.md b/gradesa/NEXTJS_APP_GUIDE.md similarity index 100% rename from gradesa/README.md rename to gradesa/NEXTJS_APP_GUIDE.md diff --git a/gradesa/data/README.md b/gradesa/data/DATABASE_MIGRATIONS.md similarity index 100% rename from gradesa/data/README.md rename to gradesa/data/DATABASE_MIGRATIONS.md diff --git a/gradesa/playwright/e2e/README.md b/gradesa/playwright/e2e/E2E_TESTS.md similarity index 100% rename from gradesa/playwright/e2e/README.md rename to gradesa/playwright/e2e/E2E_TESTS.md diff --git a/gradesa/src/SOURCE_OVERVIEW.md b/gradesa/src/SOURCE_OVERVIEW.md new file mode 100644 index 0000000..6e6cc47 --- /dev/null +++ b/gradesa/src/SOURCE_OVERVIEW.md @@ -0,0 +1,46 @@ +# src Directory Overview + +This directory contains the application source code organized by responsibility. Below is a quick guide to the main folders and notable files. + +## Top-Level Structure + +- `app/` – Next.js App Router pages, layouts, and API route handlers. Subfolders group feature areas (e.g. `auth/`, `grammar/`, `learning/`, `admin/`, `pages/` for HTML content pages, and `api/` for server endpoints). Global styles (`globals.css`) and the root `layout.js` live here. +- `backend/` – Server-side utilities and services (database access, configuration, logging, middleware wrappers, auth/session, HTML page services). Not imported client-side. Includes: + - `db.js`, `config.js`, `logging.js`, `html-services.js` + - `auth/` (password hashing + session management) + - `middleware/` (`withAuth`, `withInputValidation` and their tests, middleware README) + - `test/` backend-specific helpers/tests +- `components/` – Reusable UI components. Currently organized under `components/ui/`. +- `context/` – React context providers and related logic (e.g. user and glossary contexts). Contains its own README. +- `shared/` – Common code shared across client and server: constants, hooks, schemas (Zod), styles, small utilities. +- `styles/` – Global or feature-scoped standalone CSS not colocated with components (e.g. `anchoredExercises.css`). +- `middleware.js` – Global Next.js middleware controlling auth-based route access and redirects. + +## Common Patterns + +- API route composition uses `withAuth` and `withInputValidation` from `backend/middleware` to apply auth checks and Zod validation. +- Sessions are JWT-based (HS256) stored in an HTTP-only cookie (`AUTH_COOKIE_NAME`) via helpers in `backend/auth/session.js`. +- Database access goes through the pooled `DB` object in `backend/db.js` and transactional helper `DB.transaction`. +- Shared validation schemas are authored in `shared/schemas/` and consumed in API routes with `withInputValidation`. + +## Adding New Code + +- New server-only utilities: place in `backend/` (avoid importing them into client components). +- Reusable UI pieces: create a descriptive subfolder in `components/ui/`. +- Feature-specific page + API handlers: add under `app//` keeping route semantics. +- Shared constants or cross-cutting helpers: add to `shared/` in the appropriate subfolder. + +## Testing Notes + +- Middleware and validation have dedicated tests under `backend/middleware/`. +- Backend helpers use test flags (`isTest`) allowing session and DB swapping. + +## Conventions + +- Prefer composing API handlers with wrappers instead of duplicating auth/validation logic. +- Keep environment variable access centralized to `backend/config.js` via `getConfig()`. +- Use Zod schemas from `shared/schemas` for input validation to ensure consistent error formatting. + +--- + +For deeper details on middleware wrappers, see `backend/middleware/README.md`. For auth/session details, consult JSDoc in `backend/auth/session.js` and `backend/auth/hash.js`. diff --git a/gradesa/src/backend/middleware/README.md b/gradesa/src/backend/middleware/BACKEND_MIDDLEWARE.md similarity index 100% rename from gradesa/src/backend/middleware/README.md rename to gradesa/src/backend/middleware/BACKEND_MIDDLEWARE.md diff --git a/gradesa/src/components/ui/layout/README.md b/gradesa/src/components/ui/layout/LAYOUT_COMPONENTS.md similarity index 100% rename from gradesa/src/components/ui/layout/README.md rename to gradesa/src/components/ui/layout/LAYOUT_COMPONENTS.md diff --git a/gradesa/src/context/README.md b/gradesa/src/context/APP_CONTEXTS.md similarity index 100% rename from gradesa/src/context/README.md rename to gradesa/src/context/APP_CONTEXTS.md diff --git a/gradesa/src/shared/hooks/README.md b/gradesa/src/shared/hooks/DATA_FETCHING_HOOKS.md similarity index 100% rename from gradesa/src/shared/hooks/README.md rename to gradesa/src/shared/hooks/DATA_FETCHING_HOOKS.md