docs: add README and LICENSE with hackathon context
This commit is contained in:
MrFrostDev
@@ -0,0 +1,21 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2026 MrFrostDev
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -0,0 +1,224 @@
|
|||||||
|
<div align="center">
|
||||||
|
<img src="public/logo.png" alt="PatchPilot" width="120" />
|
||||||
|
<h1>PatchPilot</h1>
|
||||||
|
<p><strong>Repair café tool inventory & AI repair assistant.</strong></p>
|
||||||
|
<p>
|
||||||
|
<img alt="Next.js" src="https://img.shields.io/badge/Next.js-13.4-black?logo=next.js" />
|
||||||
|
<img alt="React" src="https://img.shields.io/badge/React-18-149eca?logo=react" />
|
||||||
|
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript" />
|
||||||
|
<img alt="Material UI" src="https://img.shields.io/badge/MUI-5-007fff?logo=mui" />
|
||||||
|
<img alt="License" src="https://img.shields.io/badge/license-MIT-green" />
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
PatchPilot is a small but complete web app for a repair café. It combines a
|
||||||
|
**tool inventory with a reservation system** and an **AI assistant** that helps
|
||||||
|
diagnose problems, suggest repair approaches and answer questions about the
|
||||||
|
tool database. It's designed to feel like a real product, not a wireframe.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏆 About this project
|
||||||
|
|
||||||
|
This project was built during the **Jade Hochschule AI Hackathon in May 2026**
|
||||||
|
and reached **3rd place** as a team submission.
|
||||||
|
|
||||||
|
The challenge: **vibe-code an app idea around sustainability and/or health**
|
||||||
|
in a single day. A digital companion for repair cafés fits
|
||||||
|
squarely in the sustainability bucket — repair cafés extend the lifespan of
|
||||||
|
broken things instead of sending them to landfill, and the bottleneck is
|
||||||
|
almost always tool access, expertise and coordination. PatchPilot tries to
|
||||||
|
chip away at all three at once.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✨ Features
|
||||||
|
|
||||||
|
### For everyone
|
||||||
|
- **Tool inventory** — 12 tools across 8 categories with search, filter, location, training requirements and rental period.
|
||||||
|
- **Reservation flow** — modal with date picker, live availability calendar, validation against the maximum rental period.
|
||||||
|
- **AI assistant (RepairBuddy)** — describe a problem in plain language and get a structured, Markdown-formatted answer. Supports image uploads for visual diagnosis.
|
||||||
|
- **Multi-language** — German / English with browser locale detection and persistent choice.
|
||||||
|
- **Dark / light mode** — with system-preference detection.
|
||||||
|
- **Responsive** — full mobile layout with drawers, full-screen modals and collapsing sidebars.
|
||||||
|
|
||||||
|
### For admins
|
||||||
|
- **Dashboard** with live stats (tools, users, active reservations, pending requests).
|
||||||
|
- **Pending-requests banner** with one-click approve / reject.
|
||||||
|
- **Tool CRUD** — add / edit / delete with category, emoji, location, training requirements.
|
||||||
|
- **Knowledge base** — upload manuals that are surfaced to the AI as context.
|
||||||
|
- **Reservation calendar** — month / week / day view, colour-coded by status.
|
||||||
|
|
||||||
|
### Behind the scenes
|
||||||
|
- **Role-aware AI** — the system prompt is built per request and injects a live snapshot of tools + reservations. Admins see borrower names; regular users only see availability & return dates. Same backend, different views.
|
||||||
|
- **Vision via OpenAI-compatible API** — image uploads are auto-downscaled (>2.5 MB → 1600 px JPEG) and sent as multimodal content.
|
||||||
|
- **Mock fallback** — works without an API key. The chat engine drops back to a deterministic local responder if `GEMINI_API_KEY` is missing or the upstream fails.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Getting started
|
||||||
|
|
||||||
|
### 1. Clone & install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone git@github.com:MrFrostDev/patch-pilot.git
|
||||||
|
cd patch-pilot
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Configure the AI provider
|
||||||
|
|
||||||
|
PatchPilot expects an **OpenAI-compatible chat endpoint**. It has been tested
|
||||||
|
with [Requesty](https://requesty.ai) routing to Google Gemini 3 Flash, but any
|
||||||
|
OpenAI-compatible provider works (OpenRouter, LiteLLM, vLLM, your own gateway…).
|
||||||
|
|
||||||
|
Copy the example file and fill in your credentials:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env.local
|
||||||
|
```
|
||||||
|
|
||||||
|
```env
|
||||||
|
REQUESTY_BASE_URL=https://router.requesty.ai/v1
|
||||||
|
GEMINI_API_KEY=your-key-here
|
||||||
|
PATCHPILOT_MODEL=vertex/gemini-3-flash-preview # optional, this is the default
|
||||||
|
```
|
||||||
|
|
||||||
|
If you leave the variables empty, PatchPilot uses its built-in **mock engine** —
|
||||||
|
useful for demos without burning API credits.
|
||||||
|
|
||||||
|
### 3. Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Open [http://localhost:3000](http://localhost:3000).
|
||||||
|
|
||||||
|
### 4. Sign in
|
||||||
|
|
||||||
|
Three demo accounts are bundled in the mock database:
|
||||||
|
|
||||||
|
| Username | Password | Role | Notes |
|
||||||
|
| -------- | -------- | ------------- | ------------------------------------------- |
|
||||||
|
| `admin` | `admin` | Administrator | Full access, tool CRUD, reservation actions |
|
||||||
|
| `staff` | `staff` | Staff | Has drill + soldering training |
|
||||||
|
| `guest` | `guest` | Guest | Read-only, no training |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠 Tech stack
|
||||||
|
|
||||||
|
| Layer | Choice |
|
||||||
|
| ------------------ | --------------------------------------------------------------- |
|
||||||
|
| Framework | **Next.js 13** (App Router) |
|
||||||
|
| Language | **TypeScript** (strict-ish, `strict: false` for hack speed) |
|
||||||
|
| UI library | **Material UI v5** with custom theme |
|
||||||
|
| Animation | **Framer Motion 12** |
|
||||||
|
| State | **Zustand 4** with `persist` middleware (localStorage) |
|
||||||
|
| Calendar | **FullCalendar** (dayGrid, timeGrid, interaction) |
|
||||||
|
| Icons | **lucide-react** |
|
||||||
|
| Markdown | **react-markdown** + `remark-gfm` |
|
||||||
|
| AI API | OpenAI-compatible (e.g. Requesty → Gemini 3 Flash, multimodal) |
|
||||||
|
| Fonts | **Inter** via `next/font/google` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 Project structure
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── app/
|
||||||
|
│ ├── api/chat/route.ts # Chat API — routes to live LLM or mock
|
||||||
|
│ ├── globals.css # Custom properties, FullCalendar theming
|
||||||
|
│ ├── layout.tsx # Metadata, font, providers shell
|
||||||
|
│ ├── page.tsx # AppBar + drawer + view switch + login
|
||||||
|
│ └── providers.tsx # Client-side providers (theme, i18n)
|
||||||
|
├── components/
|
||||||
|
│ ├── AIInput.tsx # Single-shell chat input with attachments
|
||||||
|
│ ├── AdminCalendar.tsx # Admin reservation calendar
|
||||||
|
│ ├── AdminDashboard.tsx # Stats + CRUD + approvals
|
||||||
|
│ ├── AnimatedBackground.tsx # GPU-composited blob background
|
||||||
|
│ ├── AvailabilityCalendar.tsx # In-modal availability view
|
||||||
|
│ ├── ChatSidebar.tsx # Session list with rename / delete
|
||||||
|
│ ├── ChatWindow.tsx # Messages, scroll-to-bottom, mode badge
|
||||||
|
│ ├── HeroSection.tsx # Landing hero with AI input
|
||||||
|
│ ├── Logo.tsx # Logo component (used everywhere)
|
||||||
|
│ ├── MarkdownMessage.tsx # Styled Markdown renderer
|
||||||
|
│ ├── Onboarding.tsx # Interactive 4-step walkthrough
|
||||||
|
│ ├── ReservationModal.tsx # Booking modal with sticky footer
|
||||||
|
│ └── ToolCard.tsx # Inventory card with hover shine
|
||||||
|
├── config/theme.ts # MUI theme (light/dark, glassmorphism)
|
||||||
|
├── services/
|
||||||
|
│ ├── auth-store.ts # Mock auth + persist
|
||||||
|
│ ├── chat-engine.ts # System prompt builder + live + mock + multimodal
|
||||||
|
│ ├── chat-store.ts # Sessions, messages, attachments
|
||||||
|
│ ├── color-mode.tsx # Theme provider with localStorage
|
||||||
|
│ ├── file-utils.ts # Image → DataURL with auto-downscale
|
||||||
|
│ ├── i18n.tsx # DE/EN dictionary + provider
|
||||||
|
│ ├── mock-data.ts # Initial tools, users, manuals
|
||||||
|
│ ├── reservation-store.ts # Reservations + status updates
|
||||||
|
│ └── tools-store.ts # Tool CRUD with persist
|
||||||
|
└── types/index.ts # Tool, User, Reservation, Category types
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧠 How the AI integration works
|
||||||
|
|
||||||
|
1. **The system prompt is built per request** (`buildSystemPrompt` in `chat-engine.ts`).
|
||||||
|
2. The current **user role** (`admin` → "Verwalter", everyone else → "Nutzer") and a **Markdown table of the live tool database** (with current reservations) are injected. This is essentially poor-man's RAG without an embedding store.
|
||||||
|
3. **Multimodal**: if the user message has image attachments, the request payload is sent as an OpenAI-style content array (`{type: 'text'}`, `{type: 'image_url'}`).
|
||||||
|
4. **Role-aware redaction is enforced by the prompt**, not by post-processing — admins see borrower names, regular users see only availability + due date. The same backend data, two views.
|
||||||
|
5. If the upstream fails (or no key is configured), the request transparently falls back to a deterministic local **mock responder** so the demo never breaks.
|
||||||
|
|
||||||
|
The system prompt itself is based on a "RepairBuddy" specification that
|
||||||
|
prioritises safety: emergency redirection to 112 / utility hotlines, no
|
||||||
|
step-by-step guides for gas / mains electricity / load-bearing structures,
|
||||||
|
honest uncertainty markers.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🖼 Image upload
|
||||||
|
|
||||||
|
- Up to 5 files per message
|
||||||
|
- Images > 2.5 MB are automatically downscaled to max 1600 px JPEG (q 0.85)
|
||||||
|
- Stored as Data-URLs in the chat store and persisted across reloads
|
||||||
|
- Rendered as clickable thumbnails inside the user bubble
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 Design notes
|
||||||
|
|
||||||
|
- **One source of truth** — colours, shadows and radii live in `theme.ts` and `globals.css` custom properties.
|
||||||
|
- **Glassmorphism AppBar** with `backdrop-filter: saturate(180%) blur(12px)`.
|
||||||
|
- **GPU-composited background** — four blurred radial blobs animated via CSS keyframes (no JS per frame). Vignette + grid pattern for foreground readability.
|
||||||
|
- **No double borders** — `AIInput` is a single shell with focus-ring; the hero just wraps it in a max-width container.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📦 Scripts
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev # development server on :3000
|
||||||
|
npm run build # production build
|
||||||
|
npm run start # serve production build
|
||||||
|
npm run lint # next lint
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🗺 Roadmap ideas
|
||||||
|
|
||||||
|
- Real auth (NextAuth + provider)
|
||||||
|
- Persistent database (Postgres + Prisma) instead of the mock store
|
||||||
|
- Real RAG with an embeddings store for manuals
|
||||||
|
- Email confirmations for approved reservations
|
||||||
|
- QR code on each tool that opens the reservation flow
|
||||||
|
- iCal export for personal reservations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 License
|
||||||
|
|
||||||
|
[MIT](./LICENSE) — do whatever you like, just don't hold me liable.
|
||||||
Reference in New Issue
Block a user