Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
phertyameen merged 1 commit into from
Aug 21, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 64 additions & 6 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,33 @@
# Contributing

Thanks for contributing to Mind Block. This document is the process; the
technical setup lives in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

## Before you start

| I need to... | Read |
| ------------ | ---- |
| Set the project up locally | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) |
| Know which environment variables to set | [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) |
| Understand the codebase layout | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| Call or extend the API | [docs/API.md](docs/API.md) |
| Run tests, lint, and builds | [docs/TESTING.md](docs/TESTING.md) |

## Contributor workflow

1. **Find an issue.** Pick an open issue and comment that you are taking it, or open one describing the problem before writing code. `good first issue` is the easiest entry point.
2. **Fork and clone.** Work on a fork; branch protection blocks direct pushes to `main` and `develop`.
3. **Set up.** Follow [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md): Node 20.x, npm, PostgreSQL, Redis, env files.
4. **Branch from `main`.** Use the naming convention below.
5. **Make the change.** Keep it scoped to the issue; unrelated refactors make review slower and merges riskier.
6. **Add tests.** New behaviour needs a spec. See [docs/TESTING.md](docs/TESTING.md).
7. **Run the local checks.** The full list is below and must pass before you push.
8. **Commit** using Conventional Commits.
9. **Open a PR** against `main` with a full description, and link the issue with `closes #<number>`.
10. **Respond to review** with follow-up commits, keeping the branch up to date with `main`.

## Import Guidelines

Rule: Always use relative imports.

Bad:
Expand All @@ -15,9 +42,10 @@ import X from "../../components/X";

CI will reject PRs containing src/* imports.

Issue/PR: https://github.com/MindBlockLabs/mindBlock_app/pull/0000 (placeholder)
## Local checks

**MUST RUN** before submitting a PR:

**MUST RUN** Local check to before submitting a pr:
```bash
npm ci
npm --workspace frontend run build
Expand All @@ -28,8 +56,13 @@ npm --workspace backend run lint

npm --workspace frontend exec -- tsc --noEmit -p tsconfig.json
npm --workspace backend exec -- tsc --noEmit -p tsconfig.json

npm --workspace backend run test
```

These mirror the CI jobs, so a clean local run means a green pipeline. Details
and troubleshooting are in [docs/TESTING.md](docs/TESTING.md).

## Contract Development

### Prerequisites
Expand All @@ -46,21 +79,26 @@ rustup target add wasm32-unknown-unknown
cargo install --locked stellar-cli
```

**MUST RUN** Local checks from inside `contracts/` before submitting a PR:
**MUST RUN** Local checks from inside `contract/` before submitting a PR:

```bash
cd contracts/
cd contract/

# Check formatting
cargo fmt --check
cargo fmt --all -- --check

# Run clippy the way CI does
cargo clippy --locked --all-targets --all-features -- -D warnings

# Build the contract
stellar contract build

# Run tests
cargo test
cargo test --locked
```

The crate directory is `contract/` (singular).

## Branch Protection
main and develop require status checks: lint-imports, build, type-check, contracts.
Require branches to be up-to-date before merging.
Expand All @@ -74,6 +112,7 @@ To maintain a clean commit history and make reviews efficient, all pull requests
- `feature/your-feature-name`
- `fix/issue-number`
- `chore/tooling-update`
- `docs/what-you-documented`
- Avoid vague names like `update` or `patch`.

### PR Title
Expand All @@ -92,6 +131,7 @@ To maintain a clean commit history and make reviews efficient, all pull requests
- **Solution**: How was it solved?
- **Acceptance Criteria**: What conditions prove the fix works?
- **Testing Notes**: How was it tested?
- Link the issue with `closes #<issue-number>`.
- Avoid minimal descriptions like only writing `Closes #22`.

### CI/CD Enforcement
Expand All @@ -100,6 +140,24 @@ To maintain a clean commit history and make reviews efficient, all pull requests
- Have descriptions shorter than 20 characters or missing context.
- The `build-and-deploy` job depends on PR validation, so failing validation will block merges.

## Code Standards

- **TypeScript everywhere** in `backend/` and `frontend/`; avoid `any` where a real type is expressible.
- **Backend layering**: HTTP concerns in controllers, business rules in providers, persistence in entities and repositories. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
- **DTOs are the contract**: the global `ValidationPipe` runs with `forbidNonWhitelisted`, so any accepted field must be declared and validated on a DTO.
- **Document new endpoints** with `@ApiOperation` and `@ApiResponse` so Swagger at `/api` stays complete, and update the matching table in [docs/API.md](docs/API.md) in the same PR.
- **New environment variables** must be added to `backend/.env.example` and documented in [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md).
- **Never commit secrets.** Env files are git-ignored; keep them that way.
- **Formatting** is handled by Prettier and ESLint. Run `npm --workspace backend run format` rather than hand-formatting.

## Documentation changes

Docs are part of the product. If your change alters setup steps, configuration,
endpoints, or commands, update the affected file under `docs/` in the same pull
request. The acceptance bar is simple: a new contributor should be able to go
from clone to a running stack with passing tests using only what is committed
here.

---

By following these standards, contributors ensure their PRs are clear, maintainable, and easy to review.
190 changes: 146 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,82 +22,180 @@ Whether you're a beginner or a pro, **Mind Block adapts to you**—making every

---

## 📚 Documentation

| Document | What it covers |
| -------- | -------------- |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Full local setup, running each service, migrations, seed data, common errors |
| [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) | Every backend, frontend, and Stellar environment variable |
| [docs/API.md](docs/API.md) | REST API reference: endpoints, payloads, auth, errors |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Monorepo layout, request lifecycle, data stores, deployment |
| [docs/TESTING.md](docs/TESTING.md) | Test, lint, type-check, and build commands, plus what CI enforces |
| [docs/CANONICAL_DOMAIN_MODEL.md](docs/CANONICAL_DOMAIN_MODEL.md) | Authoritative domain model specification |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor workflow, branch and PR standards |

---

## 🏗️ Project Structure
This is a **monorepo** containing three main components:

- **Backend (NestJS)** – API & game logic
- **Frontend (NextJS)** – User interface
- **Smart Contracts (Soroban)** – Stellar testnet deployment
- **Backend (NestJS)** – API & game logic (`backend/`)
- **Frontend (Next.js)** – User interface (`frontend/`)
- **Smart Contract (Soroban)** – Stellar testnet deployment (`contract/`)

A full directory breakdown is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

### 🌍 Hosting
- **Backend (NestJS)** → [Render](https://mindblock-webaapp.onrender.com)
- **Frontend (NextJS)** → [Vercel](https://mind-block-app-frontend.vercel.app/)
- **Contracts (Rust)** → Stellar testnet
- **Contract (Rust)** → Stellar testnet

---

## ✅ Prerequisites

| Tool | Version | Required for |
| ---- | ------- | ------------ |
| Node.js | **20.x LTS (>= 20.9.0)** | Backend and frontend. CI pins Node 20.x; Next.js 16 needs >= 20.9. |
| npm | **10.x** (ships with Node 20) | The repo uses npm workspaces and a committed `package-lock.json`. Do not use yarn, pnpm, or bun. |
| PostgreSQL | **14+** | Backend datastore. |
| Redis | **6+** | Sessions, JWT state, caching. The backend will not start without it. |
| Rust + `wasm32-unknown-unknown` | stable | Only if you work on `contract/`. |
| Stellar CLI | latest | Only for building or deploying the contract. |

---

## ⚡ Getting Started

Follow these steps to clone and set up the project locally.
The path from clone to a running stack, in order.

### 1. Clone

### 1. Clone the repository
```bash
git clone https://github.com/MindBlockLabs/mindBlock_app.git
cd mindBlock_app
```

2. Install dependencies
### 2. Install

Each package has its own dependencies. You can install them separately or at ones:
Instructions can be found in the general package.json file (script). It is advisable though to install seperately and focus on the folder your isuue is specific to.
```bash
npm ci
```

Backend (NestJS)
cd backend
npm install
This installs every workspace from the lockfile in one pass. You can also
install a single package (`cd backend && npm install`) if you only work there.

Frontend (NextJS)
cd frontend
npm install
### 3. Configure

Contracts (Soroban)
```bash
cp backend/.env.example backend/.env
printf 'NEXT_PUBLIC_API_URL=http://localhost:3000\n' > frontend/.env.local
```

Make sure you have Scarb
and Stellar CLI installed, then:
Fill in at minimum `REDIS_URL`, `JWT_SECRET`, and the `DATABASE_*` block in
`backend/.env`. Every variable is documented in
[docs/ENVIRONMENT.md](docs/ENVIRONMENT.md).

cd contracts
scarb build
### 4. Start PostgreSQL

3. Environment variables
```bash
docker run --name mindblock-postgres \
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=mindblock -p 5432:5432 -d postgres:16
```

Create a .env file inside the backend and/or frontend folders.
For backend:
Or use a local install and `createdb mindblock`. The credentials must match
`backend/.env`.

```bash
REDIS_URL=redis://127.0.0.1:6379
DATABASE_API='https://mindblock-webaapp.onrender.com/api'
### 5. Start Redis

```bash
docker run --name mindblock-redis -p 6379:6379 -d redis:7
redis-cli ping # -> PONG
```

For frontend:
### 6. Run the backend

NEXT_PUBLIC_API_URL=http://localhost:5000

4. Run the project
Backend
```bash
cd backend
npm run start:dev
```

Frontend
- API: <http://localhost:3000>
- Swagger UI: <http://localhost:3000/api>
- Health: <http://localhost:3000/health>

### 7. Run the frontend

In a second terminal:

```bash
cd frontend
npm run dev
```

Contracts
Next.js picks a free port (typically 3001 while the backend holds 3000); the
terminal prints the URL.

Deploy your Soroban contracts on Stellar testnet:
From the repo root you can also start either service without changing directory:

cd contracts
stellar-compile
stellar-deploy
```bash
npm run dev:backend
npm run dev:frontend
```

> `npm run dev` starts both through `concurrently`, which is not currently
> declared as a dependency. Until it is, either run the two commands above in
> separate terminals or install it yourself (`npm i -D concurrently`).

### 8. Run the tests

```bash
npm --workspace backend run test
npm --workspace backend run test:e2e
```

Lint, type-check, and build commands are in
[docs/TESTING.md](docs/TESTING.md).

### 9. Contract (optional)

```bash
rustup target add wasm32-unknown-unknown
cargo install --locked stellar-cli

cd contract
cargo build --locked --target wasm32-unknown-unknown --release
cargo test --locked
```

Deployment identities and network setup are covered in
[docs/ENVIRONMENT.md](docs/ENVIRONMENT.md#3-stellar-and-soroban-shell-environment).

---

## 🛠️ Common commands

| Command | Runs from | What it does |
| ------- | --------- | ------------ |
| `npm --workspace backend run start:dev` | root | Backend in watch mode |
| `npm --workspace frontend run dev` | root | Frontend dev server |
| `npm --workspace backend run test` | root | Backend unit tests |
| `npm --workspace backend run test:cov` | root | Backend coverage |
| `npm --workspace backend run lint` | root | Backend ESLint |
| `npm --workspace frontend run lint` | root | Frontend ESLint |
| `npm --workspace backend run build` | root | Compile the backend |
| `npm --workspace frontend run build` | root | Production frontend build |

---

## 🚑 Troubleshooting

Hitting `REDIS_URL not defined`, `ECONNREFUSED 5432`, `EADDRINUSE :::3000`, or a
`401` on every request? Each of those, and more, is covered in
[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#12-common-errors).

---

## 👥 Contributors & Contact

Expand All @@ -111,21 +209,25 @@ amalikabdulmalik04@gmail.com

## Contribution Guidelines

We ❤️ contributions!

Fork the repo
We ❤️ contributions! The full workflow, branch naming rules, PR standards, and
CI requirements live in [CONTRIBUTING.md](CONTRIBUTING.md). The short version:

Create a new branch:
1. Fork the repo and branch from `main`:

```bash
git checkout -b feature/your-feature-name
```

2. Make your change and run the checks in [docs/TESTING.md](docs/TESTING.md).

Commit changes with clear messages:
3. Commit with a Conventional Commits message:

```bash
git commit -m "feat: add puzzle leaderboard"
```


Push and open a Pull Request (PR).
4. Push and open a Pull Request describing the problem, the solution, the
acceptance criteria, and how you tested it.

💡 For issues/bugs, please open an issue.

Expand Down
Loading
Loading