Home / MAD2 / Week 12

Week 12 · The project: putting it all together

The one-minute story

By the end of this week you can:

• draw the architecture of a MAD2 project and say what each part is for;
• plan the folders, database tables, API routes and Vue structure for a given statement;
• explain the token flow and implement a role guard on the server and in the router;
• schedule Celery jobs (daily reminder, monthly report, async CSV export) and cache with expiry;
• run everything locally on Windows, test it, and prepare the README, report and submission;
• check your own project against a rubric and avoid the common mistakes.

Words you need

Idea 1: The architecture of a typical project

 Browser (Vue 2 SPA: components, Vue Router, Vuex)
        |  HTTP + JSON, header  Authorization: Bearer <token>
        v
 Flask API (routes, auth, roles, validation)  ---- SQLite (SQLAlchemy models)
        |                       \
        | cache get/set          \ task.delay()
        v                         v
     Redis  <------------------ Celery worker  ----> SMTP: MailHog (dev) or real server
   (cache + broker)                 ^
                                    | schedule
                              Celery beat (daily / monthly)

Core versus optional (as students report)

Typical features reported by students for MAD2 projects:

The point to remember: read your term's project statement. Marks follow it. If it makes a feature mandatory, it is mandatory, whatever this table says.

Idea 2: Folders, database and API plan

Folder structure

project/
  backend/
    app.py               # create_app(), registers extensions and blueprints
    config.py            # settings read from environment
    extensions.py        # db, jwt, cache, mail, celery objects
    models.py            # SQLAlchemy models
    routes/
      auth.py            # /api/login, /api/register
      books.py           # CRUD
      admin.py           # admin-only routes
    tasks.py             # Celery tasks and beat schedule
    templates/email/     # reminder.html, report.html
    requirements.txt
  frontend/
    src/
      main.js
      router/index.js
      store/index.js     # Vuex
      api.js             # fetch wrapper that adds the token
      components/ views/
    package.json
  README.md
  openapi.yaml           # API description
  report.pdf

Why: extensions.py avoids circular imports; routes in blueprints keep each file short; templates for emails keep HTML out of Python code. A simpler layout (a single app.py) is fine for a small project, as long as it is tidy.

Database design: design from the statement

Underline nouns in the statement: they become tables. Underline "has many": they become foreign keys. Take the library statement above.

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(50), unique=True, nullable=False)
    email = db.Column(db.String(120), nullable=False)
    password_hash = db.Column(db.String(200), nullable=False)
    role = db.Column(db.String(10), nullable=False, default="member")

class Issue(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"), nullable=False, index=True)
    book_id = db.Column(db.Integer, db.ForeignKey("book.id"), nullable=False)
    due_on = db.Column(db.Date, nullable=False)
    returned_on = db.Column(db.Date)

Store a hash (werkzeug.security.generate_password_hash) never the password. Create the admin by seeding on first run, not through a public register page.

API route plan

Use nouns, the right verb, the right status code (the earlier weeks).

OpenAPI. Describe the same table in openapi.yaml; it doubles as documentation for the examiner:

openapi: 3.0.0
info: {title: Library API, version: "1.0"}
paths:
  /api/books:
    get:
      summary: List books (paginated)
      parameters:
        - {name: page, in: query, schema: {type: integer}}
      responses:
        "200": {description: A page of books}
        "401": {description: Missing or bad token}

Idea 3: Token login, roles and guards

401 vs 403: 401 means "I do not know who you are" (no or invalid token). 403 means "I know who you are, and you may not do this".

Server side with Flask-JWT-Extended, including a role decorator (I ran this with the test client: no token gives 401, a student token on the admin route gives 403, an admin token gives 200):

from datetime import timedelta
from functools import wraps
from flask import Flask, jsonify, request
from flask_jwt_extended import JWTManager, create_access_token, jwt_required, get_jwt

app = Flask(__name__)
app.config["JWT_SECRET_KEY"] = "change-me-and-read-from-environment"
app.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)
JWTManager(app)

@app.post("/api/login")
def login():
    d = request.get_json()
    user = find_user(d.get("username"))                 # your own lookup
    if not user or not check_password(user, d.get("password")):
        return jsonify(error="bad credentials"), 401
    token = create_access_token(identity=user.username, additional_claims={"role": user.role})
    return jsonify(token=token, role=user.role)

def role_required(role):
    def deco(fn):
        @wraps(fn)
        @jwt_required()
        def wrapper(*a, **k):
            if get_jwt().get("role") != role:
                return jsonify(error="forbidden"), 403
            return fn(*a, **k)
        return wrapper
    return deco

@app.get("/api/admin/stats")
@role_required("admin")
def stats():
    return jsonify(users=2)

Your course may use a different token library (for example Flask-Security token authentication). The flow is the same: use what the lectures and the statement ask for.

Vue side: Vuex store, API helper, router guard

// store/index.js (Vuex 3)
import Vue from "vue";
import Vuex from "vuex";
Vue.use(Vuex);

export default new Vuex.Store({
  state: {
    token: localStorage.getItem("token") || null,
    role: localStorage.getItem("role") || null
  },
  mutations: {
    setAuth(state, { token, role }) {
      state.token = token; state.role = role;
      localStorage.setItem("token", token); localStorage.setItem("role", role);
    },
    clearAuth(state) {
      state.token = null; state.role = null;
      localStorage.removeItem("token"); localStorage.removeItem("role");
    }
  },
  actions: {
    async login({ commit }, creds) {
      const res = await fetch("http://localhost:5000/api/login", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(creds)
      });
      if (!res.ok) throw new Error("Login failed");
      commit("setAuth", await res.json());
    }
  }
});

// api.js
import store from "./store";
export function api(path, options = {}) {
  return fetch("http://localhost:5000" + path, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer " + store.state.token,
      ...(options.headers || {})
    }
  });
}

// router/index.js (Vue Router 3)
import VueRouter from "vue-router";
import store from "../store";

const routes = [
  { path: "/login", component: Login },
  { path: "/books", component: Books, meta: { requiresAuth: true } },
  { path: "/admin", component: Admin, meta: { requiresAuth: true, role: "admin" } }
];
const router = new VueRouter({ routes });

router.beforeEach((to, from, next) => {
  if (to.meta.requiresAuth && !store.state.token) return next("/login");
  if (to.meta.role && to.meta.role !== store.state.role) return next("/books");
  next();
});
export default router;

Idea 4: Celery jobs, caching and CORS in the project

Celery jobs

Three typical jobs (details in week 10):

Two design questions from past papers: for 1000 users, should the report job be one task per user or one task that loops? One task per user can spread over many workers; one big task is simpler but runs in series. Either can be right; state the trade-off. And for a CSV that takes 20 to 40 seconds, the front end should poll the task state (say every 3 to 5 seconds), not wait a guessed fixed time.

from celery.result import AsyncResult

@app.post("/api/export")
@role_required("admin")
def start_export():
    task = export_csv.delay()
    return jsonify(task_id=task.id), 202

@app.get("/api/export/<task_id>")
@role_required("admin")
def export_status(task_id):
    r = AsyncResult(task_id, app=celery)
    return jsonify(state=r.state, file="/static/export.csv" if r.state == "SUCCESS" else None)

Caching with expiry

Cache the read endpoints that many users repeat and that tolerate a little staleness, such as a summary or a book list. Use a TTL and delete the key when data changes (see week 11). Say your numbers: "book list, 60 seconds, deleted on add or delete".

CORS

The Vue dev server (http://localhost:8080) and Flask (http://localhost:5000) are different origins (different port), so the browser blocks the call unless Flask allows it. Install flask-cors:

from flask_cors import CORS
CORS(app, resources={r"/api/*": {"origins": ["http://localhost:8080"]}})

I tested that a request carrying Origin: http://localhost:8080 receives Access-Control-Allow-Origin: http://localhost:8080. Allow only your front end origin, not * in the final version. If the browser sends an Authorization header, it first sends an OPTIONS preflight; flask-cors answers it.

Idea 5: Run it, test it, document it

Running everything on Windows

If one of them does not start, the demo breaks, so rehearse the start-up order: Redis, MailHog, Flask, worker, beat, Vue. Write it in the README as numbered steps. Keep a requirements.txt (pip freeze > requirements.txt).

Testing

Test the backend with pytest and Flask's test client (no server needed):

def test_admin_route_needs_admin(client, student_token, admin_token):
    h = lambda t: {"Authorization": "Bearer " + t}
    assert client.get("/api/admin/stats").status_code == 401
    assert client.get("/api/admin/stats", headers=h(student_token)).status_code == 403
    assert client.get("/api/admin/stats", headers=h(admin_token)).status_code == 200

Test login (good and bad password), one CRUD path, one 404, and one validation error (400). Test the Celery task by calling the function directly (export_csv()), without a worker.

README and report checklist

• README: what the project is, how to install, exact run order, default admin login, ports, how to run tests, optional features and where they are.
• Report (short; use the template your term gives): statement, architecture diagram, database ER diagram, API list (or openapi.yaml), key design decisions, screenshots, how features map to the statement.
• Never commit venv, node_modules, .env, real passwords or webhook URLs.

Submission checklist

1. Project statement requirements ticked one by one.
2. Fresh clone works: new virtual environment, pip install -r requirements.txt, npm install, run order in the README.
3. Seed admin exists; sample data loads.
4. The .zip or repository is within the stated size and format; correct file names.
5. Report and screen-recording or links (if the term asks) in the right place before the deadline.
6. You can start every process within two minutes.

Idea 6: A six-week timeline, common mistakes and the viva

A project timeline of 6 weeks

Start week 5 early if scheduled jobs are mandatory; they need the most set-up time.

Common mistakes

• Building features not in the statement before the required ones.
• Secrets in Git (token key, SMTP password, webhook URL).
• Role checks only in the front end.
• Plain-text passwords; SQL built by string formatting.
• Heavy work inside a request (mail, PDF, CSV).
• Cache with no expiry and no invalidation; or caching personalised data under a shared key.
• Works only on your laptop (missing requirements.txt, hard-coded paths and ports).
• Forgetting CORS, then discovering it on demo day.
• Not understanding code taken from tutorials or generated by tools. The viva will find out.

How this connects to the viva

The project viva is you walking the examiner through your own work. Questions follow your code: the architecture, why this table, how login works, what the cache stores, how the job is scheduled, and "change X live". Practise with the question banks: project viva and MAD2 viva.

Exam radar

Quick quiz

Viva: say it out loud

Recap

Practise with real exam questions

These come straight from past papers (with the real figures and the official answer key). Open 34 real questions on this week   All End Term papers