changes to readme

Author: Pawan-git05

README.md

@@ -1,59 +1,133 @@
 # ResQTrack
 
-ResQTrack is a web-based coordination platform for animal rescue operations connecting citizens, NGOs, volunteers, hospitals, and donors.
+ResQTrack is a lightweight, full‑stack web app that coordinates animal rescue across citizens, NGOs, volunteers, animal hospitals and donors. Citizens can quickly report an injured animal, NGOs and volunteers can act, hospitals can be listed, and donors can contribute — all tracked end‑to‑end.
+
+The project is intentionally simple to run locally (no heavy frontend tooling) but still production‑minded on the backend (JWT auth, migrations, mail, uploads, CORS).
+
+## What this project does
+- Citizens submit rescue reports (with optional photo/video) to create an incident.
+- NGOs/volunteers coordinate response and status updates.
+- Hospital directory helps route animals to the right care.
+- Donors can record donations with automatic email receipts (if SMTP configured).
+- Admin/NGO actions use JWT for protected routes.
 
 ## Tech Stack
-- Backend: Python Flask, SQLAlchemy, SQLite by default (override to MySQL with `DATABASE_URL`), JWT, Mail
-- Frontend: HTML/CSS/JS (Bootstrap)
+- **Backend**: Flask, SQLAlchemy, Alembic (Flask‑Migrate), JWT, Flask‑Mail, Flask‑CORS, SQLite (default) or any SQL via `DATABASE_URL`.
+- **Frontend**: HTML + Bootstrap + vanilla JS. No build step. Served as static files.
 
-## Getting Started
+## Quick Start (Windows‑friendly)
 
 ### 1) Prerequisites
 - Python 3.11+
-- Optional: MySQL 8+ (only if you set `DATABASE_URL` to a MySQL URI)
+- Optional: MySQL 8+ if you plan to use MySQL instead of SQLite
 
-### 2) Clone and Install
+### 2) Setup Python environment
 ```bash
 python -m venv .venv
-.venv\\Scripts\\activate
+.venv\Scripts\activate
 pip install -r requirements.txt
-cp .env.example .env
 ```
 
-SQLite is used by default. To use MySQL, set `DATABASE_URL` like `mysql://user:pass@host:3306/resqtrack` and install `mysqlclient` (requires MSVC build tools on Windows).
+Environment file (optional): copy and adjust if you maintain one.
+```bash
+# If you have an example env
+# copy .env.example .env   (PowerShell: cp .env.example .env)
+```
+
+Key environment variables (see `backend/config.py` for defaults):
+- `SECRET_KEY`, `JWT_SECRET_KEY`
+- `DATABASE_URL` (omit to use local SQLite `resqtrack.db`)
+- `MAIL_*` (SMTP settings for email receipts)
+- `CORS_ORIGINS` (defaults to `*` for local/dev)
 
-### 3) Database Migrations
+### 3) Initialize the database
+SQLite is default; no server needed.
 ```bash
 set FLASK_APP=backend/wsgi.py
-python -m flask db init
-python -m flask db migrate -m "init"
 python -m flask db upgrade
 ```
 
-(Optional) Load sample data:
+Optional: load sample data (inspect `docs/sql/sample_data.sql`).
+
+### 4) Run the backend (API)
 ```bash
-# With SQLite, use app endpoints or insert manually via scripts
-# With MySQL:
-# mysql -u <user> -p resqtrack < docs/sql/sample_data.sql
+python backend/wsgi.py
 ```
+The API will be available at `http://localhost:5000` (health check at `/health`).
 
-### 4) Run Server
+### 5) Run the frontend (static)
+From the `frontend/` directory, serve files with a simple HTTP server:
 ```bash
-python backend/wsgi.py
+cd frontend
+python -m http.server 8000
 ```
-Visit `http://localhost:5000/health`.
+Visit `http://localhost:8000/index.html`.
+
+Front‑to‑back integration is configured via `frontend/assets/js/api.js`:
+```js
+const API_BASE = 'http://localhost:5000';
+```
+
+### Frontend UX notes
+- Images are responsive (`img { max-width: 100%; height: auto; }`) and hero/card media use object‑fit to avoid distortion.
+- The story popup on CTA buttons is disabled; buttons now navigate directly to their target pages.
+
+## End‑user flows
+- **Report**: `Report` page posts a case with optional file; returns a `case_code` for reference.
+- **Donate**: `Donate` page records a donation and sends a receipt email when SMTP is configured.
+- **Register**: `Register` page has tabs for NGO and Volunteer applications.
+- **Hospitals**: `Hospitals` page lists directory entries; admins/NGOs can add via API.
+
+## API Reference
+
+Base URL: `http://localhost:5000`
+
+### Health
+- `GET /health` → `{ status: "ok" }`
+
+### Auth
+- `POST /auth/login` body `{ email, password, role }` → `{ access_token }`
+  - roles: `ADMIN`, `NGO`, `VOLUNTEER`
+
+### Cases
+- `POST /cases` (public)
+  - Accepts JSON or multipart form data. Fields: `reporter_name?`, `reporter_phone`, `reporter_email?`, `location`, `latitude?`, `longitude?`, `animal_type?`, `urgency?`, `notes?`, and optional `file`.
+  - Response `201`: `{ message, case_id, case_code, media_url? }`
+- `PATCH /cases/<case_id>/status` (JWT required)
+  - Body `{ status }` where status is one of backend `CaseStatus` enums.
+
+### Registrations
+- `POST /register/ngo` → `201 { message, ngo_id }`
+- `POST /register/volunteer` → `201 { message, volunteer_id }`
+  - `409` on duplicate `email`.
+
+### Hospitals
+- `GET /hospitals` → `{ items: [...] }`
+- `POST /hospitals` (JWT required) → `201 { message, id }`
+
+### Donations
+- `POST /donations` → `201 { message, id }`
+  - If `donor_email` is provided and SMTP is configured, a receipt email is sent.
+
+### Uploads
+- `POST /uploads` (multipart, field `file`) → `201 { filename, url }`
+- `GET /uploads/<filename>` → serves the uploaded file
+
+### Common Errors
+- `400` Missing/invalid fields
+- `401` Invalid credentials or missing token
+- `409` Duplicate resource (e.g., `email` already registered)
 
-### 5) Frontend
-Open `frontend/index.html` in your browser. Forms call the backend APIs.
+## Data model (high‑level)
+- `AnimalCase` with `case_code`, contact/location, type, urgency, notes, optional `media_url`, and `status`.
+- `NGO`, `Volunteer`, `Hospital`, `Donation` entities with essential fields.
+- See `docs/architecture/ERD.md` and `backend/app/models.py` for complete definitions.
 
-## API Overview
-- GET `/health`
-- POST `/auth/login`
-- POST `/cases`, PATCH `/cases/<id>/status`
-- POST `/register/ngo`, POST `/register/volunteer`
-- GET/POST `/hospitals`
-- POST `/donations`
-- POST `/uploads`, GET `/uploads/<filename>`
+## Configuration & Operations
+- CORS is enabled (credentials supported). Tune origins via `CORS_ORIGINS`.
+- File uploads stored in `uploads/` by default; override `UPLOAD_FOLDER`. You can front this with a CDN or adapt to S3.
+- Mail uses standard SMTP. For Gmail, use App Passwords and set `MAIL_USERNAME`/`MAIL_PASSWORD`.
+- Migrations are managed via Alembic (Flask‑Migrate). Commit migration scripts in `migrations/` for schema changes.
 
 ## Project Structure
 ```
@@ -68,17 +142,19 @@ backend/
   wsgi.py
 frontend/
   index.html report.html register.html donate.html hospitals.html
-  assets/css styles.css
-  assets/js api.js
+  assets/css/styles.css
+  assets/js/api.js app.js
 docs/
   PRD.md
   architecture/ERD.md, DFD.md
   sql/schema.sql, sample_data.sql
 ```
 
-## Notes
-- Emails use SMTP; for Gmail, enable App Passwords and set `MAIL_USERNAME`/`MAIL_PASSWORD`.
-- File uploads are stored under `uploads/`. For S3, configure AWS env vars and extend storage logic.
+## Contributing
+1. Fork + branch from `main`.
+2. Make changes with clear commits.
+3. If you change the database, add a migration: `flask db migrate -m "..."` then `flask db upgrade` locally and include the generated script.
+4. Open a PR describing the change, rationale, and testing steps.
 
 ## License
 MIT