116 lines
No EOL
4.4 KiB
Markdown
116 lines
No EOL
4.4 KiB
Markdown
# Hackerspace Inventory
|
||
|
||
Full‑stack application for managing a small makerspace / hackerspace inventory.
|
||
**Frontend:** Vite + React + TypeScript | **Backend:** Node 20 + Express + TypeScript | **Database:** MongoDB 6+ (Atlas or local) | **Auth:** JWT (Bcrypt‑hashed passwords)
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
* **Item & Tag CRUD** – create, search, delete inventory items and their tags
|
||
* **JWT authentication** – register, login, protected routes & actions
|
||
* **Instant search** – query + tag filter (`/api/items/search`)
|
||
* **Typed everywhere** – shared TypeScript types for client & server
|
||
* **Docker‑ready** – multistage image for the production SPA (served by Nginx)
|
||
|
||
---
|
||
|
||
## 🗂️ Project Structure (monorepo)
|
||
|
||
```
|
||
.
|
||
├── backend # Express + TS + Mongoose
|
||
│ ├── src
|
||
│ │ ├── models/*.ts
|
||
│ │ ├── routes/*.ts
|
||
│ │ ├── middleware/auth.ts
|
||
│ │ └── index.ts
|
||
│ └── .env.example
|
||
├── frontend # Vite + React + TS
|
||
│ ├── src
|
||
│ │ ├── services/inventoryService.ts
|
||
│ │ ├── contexts/AuthProvider.tsx
|
||
│ │ └── …
|
||
│ ├── Dockerfile # multistage build → Nginx
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 🏃♂️ Quick Start (local dev)
|
||
|
||
### 1. Prerequisites
|
||
|
||
* Node **≥ 20**
|
||
* MongoDB **≥ 6.0** (local or Atlas URI)
|
||
* npm / pnpm / yarn
|
||
|
||
---
|
||
|
||
## 🐳 Docker (production SPA)
|
||
|
||
From `frontend/`:
|
||
|
||
```bash
|
||
docker build -t hackerspace-frontend .
|
||
docker run -p 8080:80 hackerspace-frontend
|
||
```
|
||
|
||
The built static site is served by Nginx at **[http://localhost:8080](http://localhost:8080)**.
|
||
|
||
> For a full stack containerised setup you can add a docker‑compose.yml with services for MongoDB, backend and frontend.
|
||
|
||
---
|
||
|
||
## 🔑 Environment Variables
|
||
|
||
| Variable | Location | Description |
|
||
| -------------- | --------------- | ------------------------------------------------------------------------------------------------ |
|
||
| `MONGODB_URI` | backend `.env` | Connection string to MongoDB |
|
||
| `JWT_SECRET` | backend `.env` | Secret key for signing JWTs |
|
||
| `PORT` | backend `.env` | Express port (default **3000**) |
|
||
| `VITE_API_URL` | frontend `.env` | Base URL of the backend API (default **[http://localhost:6789/api](http://localhost:6789/api)**) |
|
||
|
||
---
|
||
|
||
## 📚 API Reference
|
||
|
||
> All endpoints are prefixed with **/api/**
|
||
|
||
### Auth
|
||
|
||
| Method | Endpoint | Body | Response |
|
||
| ------ | ---------------- | --------------------------- | ----------------- |
|
||
| POST | `/auth/register` | `{ email, password, name }` | `{ token, user }` |
|
||
| POST | `/auth/login` | `{ email, password }` | `{ token, user }` |
|
||
|
||
### Tags (protected *create/delete*)
|
||
|
||
| Method | Endpoint | Description |
|
||
| ------ | ----------- | ------------------------ |
|
||
| GET | `/tags` | list all tags |
|
||
| POST | `/tags` | create `{ name, color }` |
|
||
| DELETE | `/tags/:id` | delete tag |
|
||
|
||
### Items (protected *create/delete*)
|
||
|
||
| Method | Endpoint | Description |
|
||
| ------ | ------------------------------ | ---------------------------------------- |
|
||
| GET | `/items` | list items (populated tags) |
|
||
| GET | `/items/search?query=&tagIds=` | search items |
|
||
| POST | `/items` | create `{ name, description, tagIds[] }` |
|
||
| DELETE | `/items/:id` | delete item |
|
||
|
||
Add header `Authorization: Bearer <JWT>` for protected calls.
|
||
|
||
---
|
||
|
||
## 🛠️ Useful npm scripts
|
||
|
||
| Backend | Frontend | Description |
|
||
| --------------- | --------------- | --------------------------------------------- |
|
||
| `npm run dev` | `npm run dev` | Hot‑reload development mode |
|
||
| `npm run build` | `npm run build` | TypeScript → dist / Vite production bundle |
|
||
| `npm start` | – | Start compiled backend (`node dist/index.js`) |
|
||
|
||
--- |