# Product Architecture

## What this guide does

This is the plan for what your app or website does for people.
Architecture means how the parts fit together.

You do not have to fill this in alone. Share it with the AI you use.
Tell it about your idea, your design, and the voice you chose.
Ask it one question at a time. Fix anything it gets wrong.

## Why it exists

- What do I care about?
- What problem do I want to help with?
- Who is this for?
- What would make it useful the first time they try it?

Lunchbox example: planning school lunches takes too long. A parent chooses five lunches and gets one shopping list. We start with this complete weekly task because it solves a specific problem without a long list of features.

## The first version

- What is the main thing a person should be able to do?
- What does the first version need to do that job well?
- What can wait until later?

## The screens

For each screen, write:

- What is this screen for?
- What does a person see?
- What can they tap or type?
- What happens next?
- What do they see when there is nothing saved yet?
- What do they see if something fails?
- How can they fix it or go back?

Lunchbox example: the week view shows five school days. Choose a lunch opens the meal choices. Save keeps the plan. If saving fails, the app explains what happened and keeps the choices so the parent can try again.

## The look and voice

- Which colors, fonts, and screen examples did I choose?
- How should the app sound?
- Which words or styles should it avoid?
- Can people read the words and tap the buttons with ease?
- Can people still use it with large text or a screen reader, a tool that reads the screen aloud?

## The important rules

Our canon is the agreed version everyone follows. For Lunchbox, “a week means Monday through Friday” keeps every screen and AI working from the same five-day plan. If you change the rule, update the saved plan and tell each AI.

- What must the app always do?
- What must it never do?
- Who can see or change each person’s saved information?
- Does the app need to work with no internet?
- Does it need sharing, payments, or AI? Why?

## How we will check it

- What must work before I share it?
- What should a new person be able to do with no help?
- What do I need to test on a real phone or computer?

## If the app uses AI

- What is the AI allowed to help with?
- When should it ask a question instead of guessing?
- What must it never say, share, or do?
- Which actions need the person to check and approve them?
- Which examples will we use to check its answers?

## Keep the app true to the plan

- How will people tell us what is confusing?
- When we change an idea, which files must we update first?
- What short note helps the next chat pick up where we stopped?

## Choices still open

List what we have not decided. Ask me before you fill in a guess.

## Prompt for my AI

Use this guide and the build guide to help write the full plan for my app.
Use the idea, look, and voice we agreed on.
Use short sentences and explain new words.
Go through the screens and the main task with me.
Then help turn our agreed plan into the app’s instruction files.
Do not write code yet.
