From a54fb4675ed58d4edaa86dc07a5747f22d6fb257 Mon Sep 17 00:00:00 2001 From: MrFrostDev <25389627+MrFrostDev@users.noreply.github.com> Date: Sat, 23 May 2026 13:58:27 +0200 Subject: [PATCH] docs: add README and LICENSE with hackathon context --- LICENSE | 21 +++++ README.md | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 245 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f8e1b61 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..94fb401 --- /dev/null +++ b/README.md @@ -0,0 +1,224 @@ +
+ PatchPilot +

PatchPilot

+

Repair cafΓ© tool inventory & AI repair assistant.

+

+ Next.js + React + TypeScript + Material UI + License +

+
+ +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.