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