# Project Overview — Specification Template > **How to use this file:** This is a *reference template*, not a finished spec. Give it to Claude Code together with a short description of your own product, and ask it to produce a filled-in `project-overview.md` that follows this exact structure but describes *your* project. Keep every section heading; replace the guidance and examples with your real content. Delete any section that genuinely does not apply, and say why in one line. > > The goal of this file is to give an AI coding agent **context before code** — a clear, complete picture of what the product is, who it's for, and how the pieces fit together — so that anything it builds is aligned with the whole system instead of a series of disconnected guesses. --- ## 1. One-line summary A single sentence that a stranger could read and understand what this product does. *Example:* "A booking system that lets small service businesses manage appointments and customers from their phone." --- ## 2. Problem & goal - **The problem:** What pain does this product solve, and for whom? Two or three sentences. - **The goal:** What does success look like? What should a user be able to do at the end that they couldn't before? - **Non-goals:** What this product deliberately does *not* try to do (this is as important as the goals — it keeps scope tight). --- ## 3. Target users Describe the primary user type(s). For each, note: - Who they are (role, context, technical level) - What they're trying to accomplish - The main scenario in which they use the product If there is more than one user type (e.g. an end customer and a business owner), list each separately — their needs are usually different. --- ## 4. Core features (scope) List the features that make up this version. Group them so the priorities are obvious. **Must-have (this version):** - Feature — one line on what it does and why it matters **Nice-to-have (later):** - Feature — one line, plus why it's deferred Keep this honest. A short must-have list that ships beats a long one that stalls. --- ## 5. User flows Walk through the main journeys step by step, in plain language. One flow per key task. *Example flow — "Create a booking":* 1. User opens the app and selects a service 2. User picks an available time slot 3. User enters contact details 4. System confirms and stores the booking 5. User sees a confirmation screen Cover the primary flows and the important edge cases (what happens when something is unavailable, empty, or fails). --- ## 6. System architecture (high level) Describe the shape of the system without going deep into code. The goal is that a reader understands how the parts connect. - **Frontend:** What kind of client(s)? (web, mobile, desktop) What framework family? - **Backend:** What kind of server / API? What language or framework family? - **Data storage:** What kind of database or persistence? - **External services:** Any third-party integrations (payments, auth, messaging, storage)? - **How they talk:** How does the client reach the backend? How does the backend reach data and services? > Keep this technology-agnostic if you haven't decided yet — describe the *role* of each part ("a relational database", "a REST API") rather than a specific product, and let the detailed spec files commit to specifics. --- ## 7. Data model (conceptual) List the main entities (the "nouns" of the system) and their key relationships — not full table definitions, just the shape. *Example:* - **Customer** — a person who books services - **Service** — something that can be booked (name, duration, price) - **Booking** — links a Customer to a Service at a Time - Relationships: a Customer has many Bookings; a Service has many Bookings The detailed database file (see `02-backend.md` or a dedicated data file) turns this into real schema. --- ## 8. Key rules & constraints Business rules and hard constraints that any implementation must respect. These are the things that are easy to get wrong if they aren't written down. *Examples:* - A time slot cannot be double-booked - Prices are stored in the smallest currency unit (e.g. agorot/cents) - A user can only edit their own records - All times are stored in UTC and displayed in the user's timezone --- ## 9. Design language (if relevant) If the product has a UI, capture the intended look and feel at a high level so it stays consistent. (A separate frontend file can go deeper.) - Overall tone (clean/minimal, playful, dense/professional…) - Color direction (neutral base + one accent, dark mode, etc.) - Typography direction - Any non-negotiables (accessibility, mobile-first, brand colors) --- ## 10. Open questions List anything still undecided. This tells the AI where *not* to invent an answer, and flags what you still need to think about. *Example:* - Do we support multiple businesses per account, or one? - Is payment in this version or later? --- ### Reminder for the AI reading this When you generate the real `project-overview.md` for this project: - Follow this structure and keep the section headings. - Replace all guidance and examples with the actual project's details. - Do not invent product decisions that weren't given to you — instead, add them to **Open questions**. - Stay technology-agnostic only where the project owner hasn't chosen; otherwise commit to their stack.