Setting up Flask for the API

This guide shows a minimal, debuggable Flask API using the application factory pattern. It covers the working file layout, the key files (factory, routes, template, run script), a simple debugging workflow for 404s caused by unregistered routes, and next steps for extending the API. Highlights

Application factory pattern to create and configure the Flask app.
Register routes inside the app context to ensure decorators bind to the created app.
Troubleshooting steps when every request returns 404.

Project structure (relevant files)

A short description of the files used in this example and their purpose.

Path	Purpose
`app/__init__.py`	Application factory: creates and configures the Flask app and imports routes.
`app/routes.py`	Route definitions and a simple `/routes` debug endpoint that lists registered routes.
`app/templates/base.html`	Minimal HTML template used by `/`.
`run.py`	Development entrypoint that calls the factory and runs the server.
`requirements.txt`	List of dependencies (`Flask`, etc.).
`venv/`	Virtual environment (not committed to VCS).

app/init.py

Use an application factory. Keep configuration loading minimal to start, and import (register) your routes while an application context is active so route decorators register on the created app instance.

# app/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__, instance_relative_config=True)

    # Optional: load default config (you can load from instance/config.py)
    # app.config.from_mapping(SECRET_KEY="dev")  # change in production

    # Load the instance config, if it exists (optional)
    try:
        app.config.from_pyfile("config.py", silent=True)
    except FileNotFoundError:
        pass

    # Register routes inside the app context to ensure the decorators bind to this app
    with app.app_context():
        from . import routes  # Import routes module so decorators register
        print("Routes imported successfully")

    return app

Notes:

Importing routes inside app.app_context() ensures route decorators register on the created app.
For larger projects prefer Blueprints (recommended). Importing routes inside the context is an acceptable pattern for small apps and demos.

app/routes.py

A minimal set of routes plus a helper endpoint to list registered routes. This example uses current_app (aliased as app) so the @app.route decorators attach to the application instance that created the context.

# app/routes.py
from flask import render_template, current_app as app

@app.route("/")
def home():
    return render_template("base.html")

@app.route("/about")
def about():
    return "About Page"

@app.route("/routes")
def show_routes():
    """
    Return a plain list of registered routes for debugging.
    """
    output = []
    for rule in app.url_map.iter_rules():
        output.append(f"{rule.endpoint}: {rule.rule}")
    return "<br>".join(output)

Using current_app (imported as app) and applying @app.route at module import time is fragile: it only works because create_app() imports the routes module inside an application context. For maintainability and to avoid import-time issues as your application grows, prefer defining routes in a Blueprint and registering that Blueprint from the factory.

Alternative (recommended for larger projects): define a Blueprint in this module and register it in create_app() from app/__init__.py. For this minimal app, importing routes in the app context is sufficient and simpler.

app/templates/base.html

Minimal template rendered by the / route. It includes a small block so the template can be extended later.

<!-- app/templates/base.html -->
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>My Flask App</title>
</head>
<body>
    <h1>Welcome to My Flask App</h1>
    {% block content %}{% endblock %}
</body>
</html>

run.py

Entrypoint that creates the app with the factory and runs it in development mode. Use python run.py or set FLASK_APP and use flask run.

# run.py
from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run(debug=True)

Running the application

Activate your virtual environment.

OS	Command
macOS / Linux	`source venv/bin/activate`
Windows (PowerShell)	`.\venv\Scripts\Activate.ps1`

Start the app. You have two common options:

Using Flask CLI (set FLASK_APP then run flask run) macOS / Linux:
export FLASK_APP=run.py flask run
Windows (cmd):
set FLASK_APP=run.py flask run
Or run directly:
python run.py

When Flask starts successfully you should see the factory’s print statement and server output similar to:

Routes imported successfully
 * Serving Flask app 'run.py'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit
127.0.0.1 - - [date time] "GET / HTTP/1.1" 200 -
127.0.0.1 - - [date time] "GET /routes HTTP/1.1" 200 -

Troubleshooting: 404 for all routes

If Flask starts but every request returns 404 (including /routes), check the following common causes:

FLASK_APP is not pointing to the correct entrypoint (e.g. run.py). Confirm FLASK_APP or run via python run.py.
Your app factory does not import the routes module while an application context is active, so decorators never run.
You accidentally create a second Flask app instance in routes.py (instead of using the created app) and apply decorators to that unrelated instance.

Typical symptom: server logs show the app started but /routes is not listing registered routes and every request returns 404. Fix checklist:

Import routes inside create_app() (inside with app.app_context(): from . import routes) so the module-level @app.route decorators register against the created app.
Avoid creating another Flask(__name__) in routes.py. Use current_app or, preferably, Blueprints that you register from the factory.

After applying these changes and restarting, you should see “Routes imported successfully” and get 200 responses for / and /routes.

A Chrome browser screenshot showing a "Not Found" (404) page. The page is served from localhost (127.0.0.1:5000/routes) with a message that the requested URL was not found on the server.

If you plan to extend this API, switch to Blueprints for route registration. Blueprints decouple route definitions from application creation and avoid import-time issues as your project grows. See the Flask docs for Blueprints and application factories for recommended patterns.

Next steps

Add JSON API endpoints for image upload and processing.
Implement validation and security for file uploads (size limits, allowed types).
If you serve a separate React frontend, keep Flask as a JSON API and enable CORS or use a reverse proxy (Nginx) for production deployments.
Replace the development server with a production WSGI server (e.g., Gunicorn or uWSGI) when deploying.

Links and references

Flask documentation: https://flask.palletsprojects.com/
Flask application factory pattern: https://flask.palletsprojects.com/en/latest/patterns/appfactories/
Flask Blueprints: https://flask.palletsprojects.com/en/latest/blueprints/

Course Introduction

Introduction to AI-Assisted Development

Planning Phase

Development Phase - Backend

Development Phase - Frontend

Project Completion

Setting up Flask for the API

Project structure (relevant files)

app/init.py

app/routes.py

app/templates/base.html

run.py

Running the application

Troubleshooting: 404 for all routes

Next steps

Links and references

Watch Video

​Project structure (relevant files)

​app/init.py

​app/routes.py

​app/templates/base.html

​run.py

​Running the application

​Troubleshooting: 404 for all routes

​Next steps

​Links and references

Watch Video

Project structure (relevant files)

app/init.py

app/routes.py

app/templates/base.html

run.py

Running the application

Troubleshooting: 404 for all routes

Next steps

Links and references