Plothole

Your Story, Decoded.

Plothole is an AI-powered narrative architecture tool designed for novelists, world-builders, and screenwriters. It transforms raw manuscripts and research material into a living, interconnected encyclopedia of your narrative universe.

---

🚀 Architecture: Serverless & Stateless

Plothole V2 has been refactored for a modern, serverless-first architecture optimized for Vercel.

• Runtime: Next.js 15 (App Router)
• API Layer: Stateless Serverless Functions
• Persistence: Vercel Blob (Object Storage) & JSON-based document persistence
• Authentication: Auth0 (OIDC)
• Intelligence: Google Gemini Pro/Flash via Vertex AI / Google AI SDK

---

🛠 Tech Stack

• Frontend: React 19, TypeScript, Tailwind CSS 4
• State & Routing: React Router 7, React Flow
• Editor: Tiptap (ProseMirror)
• Maps: Leaflet & OpenStreetMap (Fantasy Map Support)
• UI Components: Lucide Icons, Framer Motion

---

⚡️ Quick Start

Prerequisites

• Node.js 20+
• A Google AI Studio API Key
• A Vercel account (for Blob storage)

Installation

1. Clone the repository:

   git clone https://github.com/alittler/Plothole.git
   cd Plothole

2. Install dependencies:

   npm install

3. Environment Setup: Create a .env file based on .env.example.

4. Run for development:

   npm run dev

---

📂 Project Structure

├── app/                # Next.js App Router (API & Pages)
│   ├── api/            # Serverless route handlers
│   └── services/       # Server-side logic (Blob storage, AI extraction)
├── src/                # Frontend application
│   ├── components/     # UI Views (Atlas, Entity Explorer, Notepad)
│   ├── services/       # Client-side state & sync logic
│   └── types.ts        # Unified Type definitions
├── public/             # Static assets
└── data/               # Local fallback data templates

---

📝 License

This project is licensed under the MIT License. See the LICENSE file for the full text.

---

Built with ❤️ for Storytellers.