# CLAUDE.md

This file is project memory for Claude Code. Drop it in the repo root, `cd` into
the project, run `claude`, and Claude Code will read it automatically. Work
through the phases below **in order**, one at a time — commit after each phase.

## Project Overview

A multi-feature Flask app built with the **app-factory + blueprint** pattern.
Every feature (auth, main, and anything you add later) lives in its own
blueprint folder, so new features drop in without touching existing code.
Ships with a full authentication flow (register / login / logout) and a
public index page.

## Tech Stack

- Python 3.11+ (pyenv-managed)
- Flask 3.x — app factory pattern
- Flask-SQLAlchemy — ORM, SQLite by default
- Flask-Login — session-based auth
- Flask-WTF + WTForms — forms, CSRF protection
- Flask-Migrate — Alembic migrations
- python-dotenv — env config
- Jinja2 templates, Bootstrap 5 via CDN (swap for your own CI later)

## Target Project Structure

```
myapp/
├── app/
│   ├── __init__.py          # app factory
│   ├── models.py            # shared models (User)
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── forms.py
│   │   └── routes.py
│   └── main/
│       ├── __init__.py
│       └── routes.py
├── templates/
│   ├── base.html
│   ├── index.html
│   └── auth/
│       ├── login.html
│       └── register.html
├── static/
│   └── css/
├── config.py
├── run.py
├── requirements.txt
├── .env
└── .gitignore
```

## Conventions for Claude Code

- One blueprint per feature, under `app/<feature>/`.
- Each blueprint: `__init__.py`, `routes.py`, and `forms.py` / `models.py` only if that feature needs them.
- Templates mirror blueprint structure: feature-specific templates go in `templates/<feature>/`.
- Every template extends `templates/base.html`.
- No secrets hardcoded — config comes from environment variables via `.env`.
- Any model change → `flask db migrate` then `flask db upgrade`, never edit the DB by hand.
- When asked to "implement Phase N", only touch the files listed for that phase.

---

## Current Session Status (resume point)

Phase 0 is mostly done:
- `pyenv install 3.13 -s`, `pyenv local 3.13`, `pyenv virtualenv 3.13 venv`, and `git init` all completed.
- `.python-version` is set to `venv`.
- **Known issue:** inside the Claude Code sandboxed Bash tool, `$PATH` did not include `~/.pyenv/shims`, so the venv never actually activated in that tool — `python -V` kept resolving to the system Python.
- **Resolution in progress:** the user is activating the virtualenv manually in their own terminal (`pyenv activate venv` or equivalent), then quitting and restarting `claude` from inside that activated shell so the tool inherits the correct environment.
- **On resume:** verify with `which python` / `python -V` that the venv (Python 3.13, path containing `.pyenv/versions/3.13.14/envs/venv`) is active before running any `pip install` or `flask` commands. Once confirmed, proceed to Phase 1 (Skeleton).

---

## Build Tutorial

### Phase 0 — Environment

```bash
pyenv install 3.13 -s
pyenv local 3.13
pyenv virtualenv 3.13 venv
pyenv activate venv
git init
```

### Phase 1 — Skeleton

```bash
mkdir -p app/auth app/main templates/auth static/css
touch app/__init__.py app/models.py \
      app/auth/__init__.py app/auth/routes.py app/auth/forms.py \
      app/main/__init__.py app/main/routes.py \
      templates/base.html templates/index.html \
      templates/auth/login.html templates/auth/register.html \
      config.py run.py requirements.txt .env .gitignore
```

### Phase 2 — Dependencies

`requirements.txt`:

```
Flask==3.0.3
Flask-SQLAlchemy==3.1.1
Flask-Login==0.6.3
Flask-WTF==1.2.1
Flask-Migrate==4.0.7
python-dotenv==1.0.1
email-validator==2.1.1
```

```bash
pip install -r requirements.txt
```

`.env`:

```
FLASK_APP=run.py
FLASK_DEBUG=1
SECRET_KEY=change-me-to-a-random-string
DATABASE_URL=sqlite:///app.db
```

`.gitignore`:

```
.venv/
__pycache__/
*.pyc
instance/
.env
app.db
```

**Prompt for Claude Code:**
```
claude "Implement Phase 2 exactly as specified in CLAUDE.md: create requirements.txt, .env, and .gitignore with the given content."
```

### Phase 3 — Config & App Factory

`config.py`:

```python
import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-key-not-safe")
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL", "sqlite:///app.db")
    SQLALCHEMY_TRACK_MODIFICATIONS = False
```

`app/__init__.py`:

```python
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_login import LoginManager
from flask_migrate import Migrate
from config import Config

db = SQLAlchemy()
login_manager = LoginManager()
migrate = Migrate()

def create_app(config_class=Config):
    app = Flask(__name__)
    app.config.from_object(config_class)

    db.init_app(app)
    login_manager.init_app(app)
    migrate.init_app(app, db)

    login_manager.login_view = "auth.login"
    login_manager.login_message_category = "info"

    from app.auth.routes import auth_bp
    from app.main.routes import main_bp
    app.register_blueprint(auth_bp, url_prefix="/auth")
    app.register_blueprint(main_bp)

    from app import models  # noqa: F401 — registers models with SQLAlchemy

    return app
```

`run.py`:

```python
from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run()
```

### Phase 4 — User Model

`app/models.py`:

```python
from datetime import datetime
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash
from app import db, login_manager

class User(UserMixin, db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(64), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    password_hash = db.Column(db.String(255), nullable=False)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)

    def set_password(self, password):
        self.password_hash = generate_password_hash(password)

    def check_password(self, password):
        return check_password_hash(self.password_hash, password)

    def __repr__(self):
        return f"<User {self.username}>"

@login_manager.user_loader
def load_user(user_id):
    return User.query.get(int(user_id))
```

### Phase 5 — Auth Blueprint

`app/auth/forms.py`:

```python
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, BooleanField, SubmitField
from wtforms.validators import DataRequired, Email, EqualTo, Length, ValidationError
from app.models import User

class RegistrationForm(FlaskForm):
    username = StringField("Username", validators=[DataRequired(), Length(min=3, max=64)])
    email = StringField("Email", validators=[DataRequired(), Email()])
    password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
    confirm_password = PasswordField(
        "Confirm Password", validators=[DataRequired(), EqualTo("password")]
    )
    submit = SubmitField("Create Account")

    def validate_username(self, username):
        if User.query.filter_by(username=username.data).first():
            raise ValidationError("That username is already taken.")

    def validate_email(self, email):
        if User.query.filter_by(email=email.data).first():
            raise ValidationError("That email is already registered.")

class LoginForm(FlaskForm):
    email = StringField("Email", validators=[DataRequired(), Email()])
    password = PasswordField("Password", validators=[DataRequired()])
    remember_me = BooleanField("Remember Me")
    submit = SubmitField("Log In")
```

`app/auth/routes.py`:

```python
from urllib.parse import urlparse
from flask import Blueprint, render_template, redirect, url_for, flash, request
from flask_login import login_user, logout_user, login_required, current_user
from app import db
from app.models import User
from app.auth.forms import RegistrationForm, LoginForm

auth_bp = Blueprint("auth", __name__, template_folder="../../templates/auth")

@auth_bp.route("/register", methods=["GET", "POST"])
def register():
    if current_user.is_authenticated:
        return redirect(url_for("main.index"))
    form = RegistrationForm()
    if form.validate_on_submit():
        user = User(username=form.username.data, email=form.email.data)
        user.set_password(form.password.data)
        db.session.add(user)
        db.session.commit()
        flash("Account created. You can log in now.", "success")
        return redirect(url_for("auth.login"))
    return render_template("auth/register.html", form=form)

@auth_bp.route("/login", methods=["GET", "POST"])
def login():
    if current_user.is_authenticated:
        return redirect(url_for("main.index"))
    form = LoginForm()
    if form.validate_on_submit():
        user = User.query.filter_by(email=form.email.data).first()
        if user is None or not user.check_password(form.password.data):
            flash("Invalid email or password.", "danger")
            return redirect(url_for("auth.login"))
        login_user(user, remember=form.remember_me.data)
        next_page = request.args.get("next")
        if not next_page or urlparse(next_page).netloc != "":
            next_page = url_for("main.index")
        return redirect(next_page)
    return render_template("auth/login.html", form=form)

@auth_bp.route("/logout")
@login_required
def logout():
    logout_user()
    flash("You have been logged out.", "info")
    return redirect(url_for("main.index"))
```

### Phase 6 — Main Blueprint

`app/main/routes.py`:

```python
from flask import Blueprint, render_template

main_bp = Blueprint("main", __name__)

@main_bp.route("/")
def index():
    return render_template("index.html")
```

### Phase 7 — Templates

`templates/base.html`:

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{% block title %}MyApp{% endblock %}</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">
</head>
<body>
  <nav class="navbar navbar-expand-lg navbar-light bg-light mb-4">
    <div class="container">
      <a class="navbar-brand" href="{{ url_for('main.index') }}">MyApp</a>
      <div class="d-flex gap-2">
        {% if current_user.is_authenticated %}
          <span class="navbar-text">Hi, {{ current_user.username }}</span>
          <a class="btn btn-outline-secondary btn-sm" href="{{ url_for('auth.logout') }}">Log out</a>
        {% else %}
          <a class="btn btn-outline-primary btn-sm" href="{{ url_for('auth.login') }}">Log in</a>
          <a class="btn btn-primary btn-sm" href="{{ url_for('auth.register') }}">Register</a>
        {% endif %}
      </div>
    </div>
  </nav>

  <div class="container">
    {% with messages = get_flashed_messages(with_categories=true) %}
      {% if messages %}
        {% for category, message in messages %}
          <div class="alert alert-{{ category }}">{{ message }}</div>
        {% endfor %}
      {% endif %}
    {% endwith %}

    {% block content %}{% endblock %}
  </div>
</body>
</html>
```

`templates/index.html`:

```html
{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
  <h1>Welcome{% if current_user.is_authenticated %}, {{ current_user.username }}{% endif %}!</h1>
  {% if not current_user.is_authenticated %}
    <p>Please <a href="{{ url_for('auth.login') }}">log in</a> or
       <a href="{{ url_for('auth.register') }}">create an account</a>.</p>
  {% endif %}
{% endblock %}
```

`templates/auth/login.html`:

```html
{% extends "base.html" %}
{% block title %}Log In{% endblock %}
{% block content %}
  <h2>Log In</h2>
  <form method="POST" novalidate class="col-md-6">
    {{ form.hidden_tag() }}
    <div class="mb-3">
      {{ form.email.label(class="form-label") }}
      {{ form.email(class="form-control") }}
      {% for error in form.email.errors %}<div class="text-danger small">{{ error }}</div>{% endfor %}
    </div>
    <div class="mb-3">
      {{ form.password.label(class="form-label") }}
      {{ form.password(class="form-control") }}
      {% for error in form.password.errors %}<div class="text-danger small">{{ error }}</div>{% endfor %}
    </div>
    <div class="form-check mb-3">
      {{ form.remember_me(class="form-check-input") }}
      {{ form.remember_me.label(class="form-check-label") }}
    </div>
    {{ form.submit(class="btn btn-primary") }}
  </form>
{% endblock %}
```

`templates/auth/register.html`:

```html
{% extends "base.html" %}
{% block title %}Register{% endblock %}
{% block content %}
  <h2>Create Account</h2>
  <form method="POST" novalidate class="col-md-6">
    {{ form.hidden_tag() }}
    <div class="mb-3">
      {{ form.username.label(class="form-label") }}
      {{ form.username(class="form-control") }}
      {% for error in form.username.errors %}<div class="text-danger small">{{ error }}</div>{% endfor %}
    </div>
    <div class="mb-3">
      {{ form.email.label(class="form-label") }}
      {{ form.email(class="form-control") }}
      {% for error in form.email.errors %}<div class="text-danger small">{{ error }}</div>{% endfor %}
    </div>
    <div class="mb-3">
      {{ form.password.label(class="form-label") }}
      {{ form.password(class="form-control") }}
      {% for error in form.password.errors %}<div class="text-danger small">{{ error }}</div>{% endfor %}
    </div>
    <div class="mb-3">
      {{ form.confirm_password.label(class="form-label") }}
      {{ form.confirm_password(class="form-control") }}
      {% for error in form.confirm_password.errors %}<div class="text-danger small">{{ error }}</div>{% endfor %}
    </div>
    {{ form.submit(class="btn btn-primary") }}
  </form>
{% endblock %}
```

### Phase 8 — Wire Up & Run

```bash
flask db init
flask db migrate -m "initial: User model"
flask db upgrade
flask run
```

Visit `http://127.0.0.1:5000/` → should show the index page.
Visit `/auth/register` → create an account → redirected to `/auth/login`.
Log in → index page now greets you by username and shows "Log out".

### Phase 9 — Adding a New Feature (this is the "multiple feature" part)

Every additional feature follows the same pattern as `auth`/`main`. Example —
adding a `dashboard` feature that only logged-in users can see:

```bash
mkdir -p app/dashboard templates/dashboard
touch app/dashboard/__init__.py app/dashboard/routes.py templates/dashboard/index.html
```

`app/dashboard/routes.py`:

```python
from flask import Blueprint, render_template
from flask_login import login_required

dashboard_bp = Blueprint("dashboard", __name__, template_folder="../../templates/dashboard")

@dashboard_bp.route("/dashboard")
@login_required
def index():
    return render_template("dashboard/index.html")
```

Register it in `app/__init__.py` alongside the other blueprints:

```python
from app.dashboard.routes import dashboard_bp
app.register_blueprint(dashboard_bp)
```

Repeat this pattern for every new feature — that's the whole point of the
blueprint layout: no existing file changes when a feature is added, only new
ones.

---

## Using This File With the Claude Code CLI

1. Place `CLAUDE.md` at the project root before running `claude`.
2. Work phase by phase, e.g.:
   ```
   claude "Implement Phase 3 exactly as specified in CLAUDE.md"
   ```
3. Review the diff Claude Code produces, run/test it, `git commit`.
4. Move to the next phase. Don't skip ahead — later phases assume earlier files exist exactly as specified.

## Testing Checklist

- [ ] Can register a new user
- [ ] Duplicate email/username is rejected with a clear error
- [ ] Password is hashed, never stored in plain text
- [ ] Can log in and log out
- [ ] Index page differs for logged-in vs. anonymous users
- [ ] CSRF token present in both forms (`form.hidden_tag()`)
- [ ] `flask db upgrade` runs clean on a fresh clone

## Common Pitfalls

- Forgetting to set `SECRET_KEY` / `FLASK_APP` in `.env`.
- Circular imports between `app/__init__.py` and blueprints — always import blueprints *inside* `create_app()`, not at module top level.
- Forgetting `login_manager.login_view = "auth.login"` → `@login_required` redirects to a 404 instead of the login page.
- Running the app before `flask db upgrade` → "no such table: user".