Document a detailed readme file

README.md

@@ -1,2 +1,105 @@
-# hoa-app
-An HOA app with extra features and more centralized.
+# HOA App
+
+Full-stack web application for homeowners associations that centralizes resident accounts, announcements, community messaging, and amenity reservations. Built with React + Vite on the client and Express + MongoDB on the server, secured with JWT auth.
+
+## Features
+- Resident onboarding: registration, login, and profile updates with bcrypt-hashed passwords and JWT sessions.
+- Community updates: admins post/delete announcements; residents see them instantly across the app.
+- Message board: public community feed where residents can read and post messages.
+- Amenities: reservation links plus upload/download stubs for future file handling.
+- Single host deployment: Express serves the built React app alongside the API with CORS configured for local dev.
+
+## Tech Stack
+- Client: React 19, React Router 7, Vite, Tailwind CSS.
+- Server: Node.js, Express 5, MongoDB/Mongoose, JWT, bcrypt.
+- Tooling: ES modules throughout; dotenv for configuration; Multer/GridFS scaffolded for future uploads.
+
+## Project Structure
+```
+hoa-app/
+├── client/               # React + Vite SPA
+│   └── src/
+│       ├── pages/        # Home, Login, Register, Account, Profile, Admin, Reserve, CommunityMessages
+│       └── components/   # LoginForm, RegisterForm, AnnouncementBoard
+└── server/               # Express API
+    ├── index.js          # App bootstrap, routes, static serving
+    ├── db.js             # Mongo connection helper
+    ├── routes/           # users, announcements, community messages, (upload scaffolding)
+    ├── models/           # User, Announcement, CommunityMessages
+    └── middleware/       # authMiddleware (JWT guard)
+```
+
+## API Overview
+Base URL: `http://localhost:{PORT}` (default PORT from env, typically 3000)
+
+- **Auth / Users**
+  - `POST /api/users/register` — create resident (name, lastName, email, password).
+  - `POST /api/users/login` — returns JWT and user profile.
+  - `PUT /api/users/:id` — update name (requires Bearer token).
+  - `GET /api/users` — list users (passwords excluded).
+- **Announcements**
+  - `GET /api/announcements` — list announcements.
+  - `POST /api/announcements` — create announcement.
+  - `DELETE /api/announcements/:id` — remove announcement.
+- **Community Board**
+  - `GET /api/community/messages` — list board messages.
+  - `POST /api/community/messages` — create board message.
+
+Notes: Admin checks are not yet enforced in middleware; routes assume trusted caller. Multer/GridFS routes are scaffolded in `routes/storedFiles.js` but currently commented out.
+
+## Environment Variables
+Create `server/.env` with:
+```
+PORT=3000
+MONGODB_URI=mongodb://localhost:27017/hoa-app
+JWT_SECRET=replace-with-strong-secret
+```
+For production, also set `MONGODB_URI` to your managed cluster and choose a high-entropy `JWT_SECRET`.
+
+## Local Development
+Prereqs: Node.js 18+ and MongoDB running locally.
+
+1) Install server deps:
+```
+cd server
+npm install
+```
+2) Install client deps:
+```
+cd ../client
+npm install
+```
+3) Run the API (in `server`):
+```
+npm start
+```
+4) Run the client (in `client`):
+```
+npm run dev
+```
+The SPA serves on `http://localhost:5173` and calls the API at `http://localhost:3000`. CORS is preconfigured for that origin.
+
+## Production Build
+1) Build the client bundle:
+```
+cd client
+npm run build
+```
+2) Start the server from `server/`. Express will serve `client/dist` and the API from the same origin:
+```
+npm start
+```
+
+## Seeding an Admin (optional)
+`server/createAdmin.js` demonstrates creating an admin user; update the Mongo URI and credentials before running if you choose to seed manually.
+
+## Testing
+No automated tests are included. Recommended next steps:
+- Add API tests with Jest + Supertest.
+- Add component tests with Vitest + React Testing Library.
+
+## Roadmap Ideas
+- Enforce role-based access (admin-only announcement endpoints) via `authMiddleware`.
+- Enable file uploads/downloads using the existing Multer/GridFS scaffolding.
+- Add payments, maintenance requests, and reservation CRUD in the API.
+- Deploy with Docker or a PaaS (Railway/Render) using separate client build and server image.