Flask Project Cursor Rules – README

This README explains the Cursor Rules defined in flask_architecture_rules.mdc and how they keep your Flask codebase clean, layered, and consistent.

---

1  Why Cursor Rules?

Cursor Rules are version‑controlled system prompts that Cursor automatically injects into the AI context whenever you work inside this repository. They make sure every contributor—and the AI assistant—follows the same architecture guidelines without copy‑pasting reminders into each chat.

Put the rule file under .cursor/rules/ so it is committed with the code and shared with the whole team.

---

2  Layered Architecture Overview

Layer	Path	Responsibility
Routes	app/routes/	HTTP endpoints, request/response handling, validation. No business logic or DB access.
Services	app/services/	Business rules, orchestration, transactions. No direct SQL/ORM calls.
Integrations	app/integrations/	Thin wrappers for external APIs (YouTube, Cloudflare R2, SMTP…).
Models	app/models/	SQLAlchemy models, migrations, CRUD helpers.

The Rules enforce the import flow → routes → services → integrations|models (no upward or circular imports).

---

3  Key Enforcement Points

1. No data‑access code outside app/models/.
2. No business logic inside app/routes/.
3. Public functions must include type hints and docstrings.
4. Custom AppError exceptions propagate upward; routes translate them into HTTP responses.
5. Unit tests should mock lower layers to keep boundaries clear.

These checks are applied automatically when AI generates or edits code in matching globs declared in the .mdc file.

---

4  Directory & File Placement

project_root/
│  README.md                ← you are here
│
└─ .cursor/
   └─ rules/
      ├─ flask_architecture_rules.mdc   ← actual rule definitions
      └─ … (add more rule files as needed)

Add more rule files for other concerns (frontend, CI workflows, coding style guides). Cursor will merge all active rules into the context.

---

5  Extending or Modifying the Rules

1. Edit flask_architecture_rules.mdc to tweak responsibilities, add new globs, or change descriptions.
2. Commit changes so every team member benefits.
3. (Optional) Run /Generate Cursor Rules in a Cursor chat to let the AI summarize new decisions into a fresh rule file.

---

6  Getting Help

If the AI suggests code that violates these rules, remind it by referencing the rule file in chat: @flask_architecture_rules. Cursor will re‑inject the rule into the context for that conversation.

Enjoy a predictable, clean Flask codebase! ✨