# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

**Prumo** — gerente de projetos e tarefas (project & task manager).
Stack: Python 3.14, Flask 3.1, SQLAlchemy 2, Flask-Login + Authlib (Google OAuth), Jinja2 templates.
Dev DB: SQLite. Prod DB: MySQL on cPanel Passenger WSGI at `app.prumoboard.com`.

## Running Locally

```bash
cd app
flask --app app run --debug
```

Dependencies: `pip install -r app/requirements.txt`. Virtual env is at `.venv/` (Python 3.14).

Health check to confirm the app is up: `curl http://localhost:5000/health/`

## Deployment

**After every `git push` in this project, always run `python deploy.py` immediately.**

`deploy.py` calls `POST https://app.prumoboard.com/health/deploy` (Bearer token from `deploy.ini [deploy] token`). The endpoint on the server runs `git pull origin main`, `pip install`, and `touch tmp/restart.txt` to restart Passenger. Credentials are in `deploy.ini` (gitignored).

GitHub Actions (`.github/workflows/deploy.yml`) exists but cannot be used — GitHub Actions is unavailable due to a payment issue on this account. `deploy.py` is the permanent deploy mechanism for now.

## Architecture

### Factory & entry points

`app/app.py` exports `create_app()` — no routes there, only blueprint registration and extension init.
`passenger_wsgi.py` (root) is the production WSGI entry point; it calls `create_app()` and exposes `application`.

### Blueprints

Routes live in `app/routes/<context>/`, one subfolder per concern. Each folder has an `__init__.py` that exports the blueprint for clean imports. `create_app()` calls `app.register_blueprint(...)` for each.

Currently implemented:
- `routes/health/` — diagnostic endpoints (`/health/`, `/health/ping`, `/health/hello`) and `POST /health/deploy` (webhook de deploy)
- `routes/main/` — landing (`GET /`), `GET /login`, `GET /register`, and `GET /dashboard` (`@login_required`)
- `routes/auth/` — `POST /auth/register`, `POST /auth/login`, `GET /auth/logout` (email/password via Flask-Login)

Planned (not yet implemented): Google OAuth routes in `routes/auth/` (Etapa 7).

### Configuration

`app/config.py` — a single `Config` class. Sensitive values come from `.env` (never committed; see `.env.example`). Key vars: `SECRET_KEY`, `DATABASE_URL`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `DEPLOY_TOKEN`.

### Models & services

`app/models/user.py` — `User` model (id, email, name, password_hash, google_id, created_at); inherits `UserMixin` and has `set_password`/`check_password`. Run `flask --app app create-db` to create tables.
`app/services/auth_service.py` — `register_user`, `authenticate_user`, and `AuthError`. Google OAuth helpers planned for Etapa 7.

## Execution plan (handoff)

The project follows a phased handoff in `issues/start/start-handoff.md`:

| Stage | Topic | Status |
|-------|-------|--------|
| 1 | Flask factory + folder structure | ✓ done |
| 2 | Health check blueprint | ✓ done |
| 3 | GitHub repo + cPanel deploy | ✓ done |
| 4 | SQLAlchemy + User model | ✓ done |
| 5 | Landing page templates | ✓ done |
| 6 | Email/password auth | ✓ done |
| 7 | Google OAuth | pending |
| 8 | Dashboard + logout | pending |

Always check this plan before starting a new stage.

## Key constraints

- `deploy.ini` is gitignored — never commit it.
- The production virtualenv on cPanel runs Python 3.13 (pyenv on dev uses 3.14 — keep compatible).
- No test suite yet; verify behaviour with `curl` against the health endpoints.

## Issues

Issues are recorded under `issues\<topic>\<subtopic1>...<subtopicN>\<issue-name>\`
(e.g. `issues\personal\sunrise-walk\`). Each issue folder holds a context file
first (`<issue-name>-context.md`), and later a step-by-step handoff file
(`<issue-name>-handoff.md`) once implementation planning starts.

## Language

- All identifiers in source code (variables, functions, classes, modules, routes, DB tables/columns, etc.) must be in English.
- The user-facing interface (templates, UI copy, messages) will initially be in English.