Homework Central

Homework Central is a full-stack web application with a React + Vite frontend, an ASP.NET Core API, and PostgreSQL for persistence. Local development is orchestrated by scripts in scripts/ that start Docker services (Postgres and FCaptcha), build the stack, and launch the API and frontend.

---

Prerequisites

Install the following before running the project locally.

Requirement	Version	Notes
Docker	Latest	Docker Desktop on Windows/macOS, or the Docker Engine on Linux. Must be running before you start the dev stack.
.NET SDK	10.x	See global.json for the pinned SDK version. Download .NET.
Node.js	18+	Includes npm, used for frontend dependencies. Download Node.js.
PowerShell	7+ (pwsh)	Windows only — required by the .ps1 scripts. Install PowerShell.
Bash	Any recent shell	Linux / macOS — used by the .sh scripts.

First-time setup: Clone the repository, ensure Docker is running, then use one of the run commands below. The scripts create a .env file automatically with generated secrets.

---

Quick start

Windows (PowerShell)

From the repository root in PowerShell 7+:

# Start the full dev environment (Postgres, FCaptcha, API, frontend)
.\scripts\run-dev.ps1

To wipe the local database (removes all registered accounts and seed data) and start fresh:

.\scripts\reset-dev-db.ps1 -Yes && .\scripts\run-dev.ps1

Linux / macOS (Bash)

From the repository root:

# Start the full dev environment
./scripts/run-dev.sh

To reset the database and start fresh:

./scripts/reset-dev-db.sh --yes && ./scripts/run-dev.sh

On Unix, make scripts executable if needed: chmod +x scripts/*.sh

---

What the dev stack starts

After a successful run, these services are available:

Service	URL	Description
Frontend	http://localhost:5173/login	React app (Vite dev server)
API	http://localhost:5000	ASP.NET Core backend
Health check	http://localhost:5000/healthz	API readiness probe
Postgres	localhost:5434 (default)	Docker container; port configurable via .env
FCaptcha	localhost:3010 (default)	Self-hosted captcha service (Docker)

On Windows, the API and frontend each open in a separate terminal window. On Linux/macOS, both run in the current terminal (use Ctrl+C to stop).

The browser opens automatically when servers are ready.

---

Common commands

Run only (keep existing data)

Platform	Command
Windows	.\scripts\run-dev.ps1
Linux / macOS	./scripts/run-dev.sh

Reset database, then run

Platform	Command
Windows	.\scripts\reset-dev-db.ps1 -Yes && .\scripts\run-dev.ps1
Linux / macOS	./scripts/reset-dev-db.sh --yes && ./scripts/run-dev.sh

Stop the dev stack

Platform	Command
Windows	.\scripts\stop-dev.ps1 (close API/frontend terminals manually)
Linux / macOS	./scripts/stop-dev.sh or Ctrl+C in the run terminal

Build without starting servers

Platform	Command
Windows	.\scripts\run-dev.ps1 -BuildOnly
Linux / macOS	./scripts/run-dev.sh --build-only

Help

Platform	Command
Windows	.\scripts\run-dev.ps1 -Help
Linux / macOS	./scripts/run-dev.sh --help

---

Project layout

Homework-Central/
├── backend/HomeworkCentral.Api/   # ASP.NET Core API
├── frontend/                      # React + Vite SPA
├── scripts/                       # Dev orchestration (.ps1 / .sh)
├── docker-compose.yml             # Postgres, FCaptcha, and production-style services
├── HomeworkCentral.sln            # .NET solution
└── global.json                    # Pinned .NET SDK version

---

Troubleshooting

• Docker not running — Start Docker Desktop (or the Docker daemon) and retry.
• Port already in use — Another Postgres install may own 5434 on localhost. The run scripts try to pick a free port and update .env; you can also set POSTGRES_HOST_PORT manually.
• Stale database volume — Run the reset command above (reset-dev-db with -Yes / --yes), then run-dev again.
• Skip Docker — If you already have Postgres on localhost: .\scripts\run-dev.ps1 -SkipDocker (Windows) or ./scripts/run-dev.sh --skip-docker (Unix).

---

License

See the repository for license details.