docs: add comprehensive API and environment documentation (#627)

[arandomogg]

Problem

The root README documented a setup flow that no longer matches the repository. It pointed at a contracts/ directory that does not exist, listed only three backend environment variables, gave no Node or package-manager requirement, and said nothing about PostgreSQL, Redis, migrations, seed data, or how to run the test suite. There was no API reference outside the generated Swagger page, no environment reference, and no architecture overview. A new contributor could not get from clone to a running stack with passing tests without asking a maintainer.

Solution

Added a contributor-oriented documentation set under docs/ and rewrote the root README and CONTRIBUTING to point at it. Every command, variable, path, and default below was read out of the codebase rather than assumed.

New files

docs/API.md - REST reference for the NestJS backend: base URLs and the Swagger mount point, the bearer-token model and the exact public prefixes excluded from JwtAuthMiddleware (auth, api, docs, health), validation semantics under forbidNonWhitelisted, the error-status table, throttling, pagination defaults, and CORS. Then every route grouped by area (auth, health, users, puzzles, categories, game sessions, challenge attempts, progress, daily quest, streaks, analytics, blockchain, admin), with request bodies taken from the DTOs, real enum values for PuzzleDifficulty and GameSessionStatus, and a three-step Stellar wallet login walkthrough.

docs/ENVIRONMENT.md - Every environment variable in the repo, grouped by concern, each with required/default/description and the file that reads it. Covers the backend runtime, PostgreSQL including DATABASE_URL taking priority over the discrete variables, the separate DB-prefixed set that data-source.ts uses for the TypeORM CLI, Redis, JWT, Google OAuth, SMTP, and ADMIN_HEALTH_KEY; then the frontend variable and the Stellar CLI shell variables needed for deploys. Includes copy-paste templates for the backend and frontend env files and a pre-flight checklist.

docs/DEVELOPMENT.md - The clone to install to configure to PostgreSQL to Redis to backend to frontend to tests path, in order, with Docker and native options for both datastores. Documents prerequisites with versions, npm workspaces usage, every backend and frontend script, the contract toolchain, the current state of migrations and seed data, and a common-errors section covering the missing REDIS_URL boot failure, connection refusals on 5432 and 6379, port 3000 already in use, blanket 401s from the global JWT middleware, the property-should-not-exist rejection from the validation pipe, the absolute-import CI rejection, Node version mismatches, and the ed25519-dalek pin.

docs/ARCHITECTURE.md - Component diagram, annotated repository layout, the backend module/controller/provider layering, the full request lifecycle from correlation ID through to the exception filter, a cross-cutting-concerns table covering config, persistence, caching, auth, authorization, rate limiting, scheduling, events, docs, and shutdown, the domain flow of a play-through, frontend stack, contract notes, data stores, and deployment targets.

docs/TESTING.md - What is testable today per package, every backend Jest command with narrowing examples, whether infrastructure is needed for unit versus e2e specs, a spec template, contract checks, lint, type-check, build, the full pre-PR sequence, an exact breakdown of both CI workflows and their job names, and a failure-debugging table.

Updated files

README.md - Kept the product introduction and hosting section; replaced the setup section with a prerequisites table (Node 20.x LTS 20.9 or newer, npm 10.x, PostgreSQL 14 or newer, Redis 6 or newer) and a numbered clone to install to configure to database to Redis to backend to frontend to tests path that matches the acceptance criteria. Added a documentation index, a common-commands table, and a troubleshooting pointer. Corrected the contracts/ references to contract/ and replaced the non-existent Stellar build commands.

CONTRIBUTING.md - Added a before-you-start routing table, an explicit ten-step contributor workflow, a code-standards section covering the DTO contract, Swagger annotations, documenting new environment variables, and secrets, a documentation-changes policy, and docs branch naming. Kept the existing import rule, local checks, branch protection, and PR standards intact, correcting the contract directory name and aligning the contract checks with what CI actually runs.

Accuracy notes

Where the code and the ideal state differ, the docs describe reality and flag the gap rather than documenting something that does not work:

• backend/data-source.ts reads DB-prefixed variables while the app reads DATABASE-prefixed ones, its migrations glob resolves to backend/migrations/ while the files live in backend/src/database/migrations/, and its entities glob is missing a path separator.
• DATABASE_SYNC and DATABASE_LOAD are mapped to the strings true and false in database.config.ts, so both read as truthy whatever you set.
• backend/src/seed.ts is a scaffold with no seeders wired in and no npm script.
• The root dev script calls concurrently, which is not declared in any package.json and is absent from the lockfile.
• frontend/lib/stellar/api.ts hard-codes the localhost backend URL instead of reading NEXT_PUBLIC_API_URL.
• The frontend has test files but no configured test runner.
• The root workspaces array lists contracts and middleware, neither of which exists.

Each is called out as a known gap with a workaround, and several are noted as good follow-up PRs. This change is documentation only; no source or configuration files were touched.

Acceptance Criteria

• docs/API.md, docs/ENVIRONMENT.md, docs/DEVELOPMENT.md, docs/ARCHITECTURE.md, and docs/TESTING.md all exist
• README.md and CONTRIBUTING.md updated and cross-linked to the new set
• Required Node version and package manager documented
• PostgreSQL and Redis setup documented, with Docker and native options
• Backend, frontend, and Stellar environment variables documented
• Migrations and seed data documented, including current limitations
• Test, lint, and build commands documented for every package
• Common errors documented with causes and fixes
• Contributor workflow documented end to end
• A new contributor can go from clone to install to configure to database to Redis to backend to frontend to tests using only committed instructions

Testing Notes

• Every documented command was cross-checked against the scripts blocks in the root, backend, and frontend package.json files; commands that do not work as written, such as the root dev script, are flagged rather than listed as working.
• Environment variables were enumerated by grepping for process.env across backend/src, backend/data-source.ts, backend/scripts, and the frontend, then traced to the config file that reads each one.
• The endpoint tables were built from the Controller and HTTP-method decorators in every controller, with payload fields read from the corresponding DTO classes and enum values read from the enum definitions.
• CI job names, Node version, and the exact check commands were taken from the two workflow files in .github/workflows.
• All relative links and heading anchors between the new documents were verified to resolve.
• Documentation only, so no code paths change; existing lint, type-check, build, and test behaviour is unaffected.

closes #627

[vercel]

@arandomogg is attempting to deploy a commit to the aminubabafatima8-gmailcom's projects Team on Vercel.

A member of the Team first needs to authorize it.