🚀 Hackademia

An Uber‑like instant help platform that connects consumers and providers in real time — with AI auto‑tagging, voting, negotiation, and a community forum. Built with a FastAPI backend and a Flutter mobile app.

---

🌈 Why Hackademia?

• Instant Help: Request services and get matched with nearby providers.
• Community Power: Raise issues, discuss in forums, vote, and prioritize what matters.
• AI‑Smart: Auto‑tag issues, suggest schedules, and assist with negotiations.
• Fair & Transparent: Voting, offers/counter‑offers, ratings, and history — all in one place.

---

🧭 Table of Contents

1. Features
2. Architecture
3. Screenshots / Demo
4. Getting Started
   • Backend (FastAPI)
   • Mobile App (Flutter)
5. API Highlights
6. Tech Stack
7. Project Structure
8. Troubleshooting
9. Roadmap
10. Contributing
11. License

---

✨ Features

• Auth: JWT‑based signup/login, user profiles.
• Providers: Skills, location, availability, ratings.
• Consumers: Post requests, browse providers, track bookings.
• Bookings: Request → accept/decline → scheduled → completed/canceled.
• Forum/Issues: Create issues with images, discuss, upvote/downvote.
• AI: Auto‑tagging, image‑assisted tagging, schedule suggestions.
• Negotiation: Offers, counter‑offers, and intelligent negotiation flows.
• Fundraising: Optional flows to raise and allocate funds for issues.

---

🏗 Architecture

• Backend: FastAPI + SQLite (local dev), JWT Auth, uploads, AI utilities
• Mobile: Flutter app with role‑based flows (Consumer/Provider)
• Communication: REST APIs; Swagger at /docs

┌──────────────── Hackademia Monorepo ────────────────┐
│                                                      │
│  backend/  ← FastAPI app (Auth, Providers, Bookings, │
│               Issues/Forum, AI, Negotiation, Uploads)│
│                                                      │
│  mobile_app/ ← Flutter app (UI, Role flows, Forum,   │
│                 Provider dashboard, booking journey) │
│                                                      │
└──────────────────────────────────────────────────────┘

---

📸 Screenshots / Demo

Add your screenshots/GIFs here for instant visual appeal:

---

## 🛠 Getting Started

### 1) Backend (FastAPI)

1. Create and activate a virtual environment (Windows PowerShell)
   ```powershell
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1

2. Install dependencies (run from repo root)

   pip install -r backend\requirements.txt

3. Configure environment (optional; defaults work for local dev). Create/edit backend/.env:

   SECRET_KEY=dev-secret-change-me
   ACCESS_TOKEN_EXPIRE_MINUTES=60
   JWT_ALGORITHM=HS256
   DATABASE_URL=sqlite:///./data.db
   CORS_ALLOW_ORIGINS=*
   UPLOAD_DIR=./uploads

4. Run the server

   uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

5. Open API docs
   • Swagger UI: http://localhost:8000/docs

Notes:

• DB: SQLite file at backend/data.db (auto‑created on startup).
• Uploads: Served at /uploads (directory: backend/uploads).

2) Mobile App (Flutter)

1. Prereqs: Flutter SDK (3.x), Android/iOS tooling
2. Set API base URL
   • Edit mobile_app/lib/config/api_config.dart and set:

   static const String baseUrl = "http://<YOUR_LAN_IP>:8000"; // e.g., http://192.168.1.50:8000

3. Get packages and run

   Set-Location mobile_app
   flutter pub get
   flutter run

---

🔌 API Highlights

• Auth
  • POST /api/auth/signup, POST /api/auth/login, GET /api/auth/me
• Providers
  • GET /api/providers/nearby?lat=..&lng=..&within_km=..&skill=cleaning
• Consumers
  • GET/PUT /api/consumers
• Bookings
  • POST /api/bookings · GET /api/bookings · PATCH /api/bookings/{id} (status: requested|accepted|declined|scheduled|completed|canceled)
• Issues/Forum
  • POST /api/issues (use ?analyze=true to auto‑tag) · GET /api/issues?sort=trending
• AI
  • /api/ai/auto-tag, /api/ai/auto-tag-with-image, /api/ai/schedule
• Voting
  • POST /api/votes/{issue_id} with {value: 1|-1}
• Negotiation
  • /api/negotiation/start, /api/negotiation/chat, /api/negotiation/session, plus intelligent variants under /api/negotiation/intelligent/*

---

🧰 Tech Stack

• Backend: FastAPI, Pydantic, SQLite (dev), JWT, Uvicorn
• Mobile: Flutter, Dart
• AI: Transformers/PyTorch utilities (for tagging/translation where available)

---

📂 Project Structure

Hackademia/
├─ backend/               # FastAPI app and dependencies
│  ├─ app/                # API, models, services, AI helpers
│  ├─ uploads/            # Static served uploads
│  ├─ requirements.txt
│  └─ .env                # Local env (create it)
├─ mobile_app/            # Flutter application
│  ├─ lib/                # Dart code
│  ├─ assets/             # Images, fonts, etc.
│  └─ pubspec.yaml
└─ README.md              # You are here 🎉

---

🪛 Troubleshooting

• Mobile can’t reach backend: Use your machine’s LAN IP (not localhost) in ApiConfig.baseUrl.
• CORS errors: Adjust CORS_ALLOW_ORIGINS in backend/.env, then restart the server.
• DB issues: Delete backend/data.db in dev to reset. Ensure write permission for backend/.
• Uploads: Ensure backend/uploads exists (auto‑created on startup).

---

🗺 Roadmap

• Push notifications for booking status updates
• In‑app payments and escrow
• Offline mode (mobile)
• Advanced provider analytics
• Multi‑tenant deployment guide

---

🤝 Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/amazing
3. Commit: git commit -m "feat: add amazing"
4. Push: git push origin feat/amazing
5. Open a Pull Request — PRs welcome!

---

📄 License

TBD — See LICENSE when available.

---