Flask Setup Guide

Flask is a lightweight web framework for Python. It lets you build web applications — pages people can visit in a browser, forms they can fill out, and data they can interact with.

If you have never built a website before, that is okay. Flask handles the hard parts of web development so you can focus on what your app does.

Quick Setup

If you have not used uv before, review the Packages and uv guide first.

Open your terminal, navigate to your project folder, and run:

uv init
uv add flask

Create a file called app.py:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def home():
    return "Hello, world!"

Run it:

uv run flask run --debug

Open your browser to http://127.0.0.1:5000 and you should see "Hello, world!" on the page. The --debug flag makes Flask reload automatically when you save changes, so you do not need to restart the server every time.

Press Ctrl+C in your terminal to stop the server.

How Flask Works

Flask connects URLs to Python functions. When someone visits a URL, Flask runs the matching function and sends the result back to the browser.

@app.route("/about")
def about():
    return "This is the about page."

Visit http://127.0.0.1:5000/about and you see "This is the about page." Each @app.route() is called a route — it maps a URL path to a function.

Adding HTML Templates

Returning plain strings gets old fast. Flask uses templates (HTML files with placeholders) to build real web pages.

Create a templates/ folder and add a file called home.html:

<!DOCTYPE html>
<html>
<head>
    <title>{{ title }}</title>
</head>
<body>
    <h1>{{ title }}</h1>
    <p>Welcome to my app!</p>
</body>
</html>

Update app.py to use the template:

from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def home():
    return render_template("home.html", title="My App")

The {{ title }} parts are placeholders that Flask fills in with the values you pass to render_template().

Recommended Project Structure

my-project/
├── app.py              # Your Flask app (routes and views)
├── helpers.py          # Your business logic (data processing, etc.)
├── templates/          # HTML templates
│   ├── base.html       # Shared layout (header, footer, nav)
│   ├── home.html
│   └── ...
├── static/             # CSS, images, JavaScript
│   └── style.css
├── data/               # Data files (CSV, JSON, etc.)
├── pyproject.toml      # Dependencies (created by uv)
└── README.md

Put your routes in app.py and your core logic in helpers.py (or a separate module). This keeps your code organized and makes it easier for you to explain what you built.

Project Ideas

Here are some ideas that are realistic for a 3-week timeline. Pick one that interests you and scope it down to the simplest version that works.

Campus Event Board — A page that lists upcoming events. Users can add new events through a form. Store events in a JSON file or simple database. MVP: one page that lists events, one form that adds them.

Quiz App — A web app that presents multiple-choice questions and tracks your score. Load questions from a data file. MVP: show one question at a time, track right/wrong, show final score.

Recipe or Bookmark Manager — Save and organize links or recipes. Add tags or categories. MVP: a form to add items, a page to list them, and the ability to delete.

Personal Dashboard — A single page that pulls together information you care about (weather, to-do list, quotes, class schedule). MVP: display 2-3 sections with hardcoded or file-based data.

Tutorials and Resources

Flask Quickstart — the official first steps guide, covers routes, templates, and the development server
Flask Official Tutorial — builds a complete blog app from scratch with database, auth, and deployment
DigitalOcean: How To Make a Web Application Using Flask — beginner-friendly walkthrough with clear explanations
Real Python: Build a Scalable Flask Web Project — covers project layout, templates, blueprints, and static files

Agent Prompts

Use these prompts with your coding agent (Cursor, Claude Code, etc.) to get started. Copy and paste them, then modify to fit your project.

Brainstorm and plan your app:

Read my project.spec.md. I want to build a Flask web app that [describe your idea]. Help me think through the pages I will need, what data the app will store, and what the simplest working version looks like. Ask me questions to narrow it down.

Scaffold your project:

Read my project.spec.md and set up a Flask project based on my plan. Create app.py with the basic routes, a base.html template with a simple layout, and one page template for the home page. Explain each file you create so I understand how they connect.

Learn Flask concepts as you build:

I just added a new route to my Flask app but I do not understand how templates work yet. Look at my app.py and templates/ folder, then explain how render_template connects my Python code to the HTML. Show me how to pass a list of items to a template and loop through them.

Add a form:

I need a page where users can submit data through a form. Look at my app.py and show me how to create a route that handles both GET (show the form) and POST (process the submission) requests. Explain what each part does. Use a simple HTML form — no JavaScript needed.