SUBTASK #49: Application entry point and Application Controller (2.0)

Open
  • Is something wrong?
#50 0 comments 0 reactions 1 assignee View on GitHub

@javi120467 is already working on this.

Since Oct 28, 2026.

  • #99 by @Titus0341 — open

Assessment

This issue has not been assessed yet.

Description

backend High Priority subtask

What to do

Create the real application: backend/main.py, the one place where every object is built and the web server is started, and the Application Controller (2.0), the Flask app that every request passes through. The controller checks access (a placeholder until M4), sends each request to the right service, and turns every error into JSON. The scan and device routes are added in subtask 2; this subtask builds the frame they plug into.

Background

  • Spec: NFR-01, NFR-02 (UI, processing and storage kept separate), SEC-01 / SEC-03 (authentication and roles, M4), SEC-08 and POL-03 (no credentials or sensitive details in logs or responses)
  • System design 2.0: "receives a request, asks 2.1 to validate the session and authorize the action, decides whether to route or reject, routes to the right manager, and returns a response." Section 3, tier rules.
  • OOD: ApplicationController.handleRequest(), routeRequest(), checkPermissions(); the controller "triggers alerts after a committed outcome"
  • Design document section 12: Flask
  • Rules are in #49.

Steps

backend/main.py: the entry point (py -m backend.main)
  • Reads the settings from .env, creates one DatabaseEngine, the data access stores (3.1, 3.2, 3.3), the ScanSessionController and the ScanManager, and passes them into the controller. Nothing else in the app creates these objects.
  • Gathers the services into one small Services record (scan manager, scan sessions, devices, users), so the controller receives one object, and tests can build one from fakes
  • Starts Flask on 127.0.0.1 only, port from APP_PORT (default 5000), debug mode off
  • Sets up Python logging (to the console) once, here
  • Clear start-up failures instead of tracebacks: database unreachable (the same message as check_connection), or the development user missing (see below)
backend/controller/app_controller.py: the Application Controller (2.0)
  • create_app(services, dev_user) -> Flask: the app factory, same shape as the dev server's
  • TRUSTED_HOSTS = ["127.0.0.1", "localhost"] and JSON keys kept in order
  • Access check before every request (before_request): check_permissions() decides who is calling and stores it for the route.
    • Placeholder until M4: every request acts as the development user named by DEV_USERNAME in .env, looked up once at start-up (it must already exist in app_user). Marked # PLACEHOLDER (M4) with a docstring explaining what 2.1 will replace.
  • Errors are always JSON {"error": "..."}:
    • Flask errors (404, 405, 400) use their normal codes
    • Unexpected exceptions: 500 with a generic message ("Something went wrong; see the server log"). The details go to the log, never the response, unlike the dev server. This is the product, and stack traces can reveal internals (SEC-08).
  • GET /api/health: {"status": "ok", "database": "ok"}, or "database": "unavailable" with status 503, so the screens and a person can tell "the app is up but MySQL isn't"
  • A register_routes(app, services) hook that subtask 2 fills in, so routes live in their own module rather than growing this file
  • on_scan_finished(result): passed to the Scan Manager as on_finished. Logs the outcome and summary, and logs which alerts would be sent ("scan failed", new flagged devices). Sending email is M6 (SH-3).
Tests: tests/controller/test_app_controller.py
  • Use Flask's test client with fake services, so no database or network
  • /api/health is OK with a working fake, and 503 with a failing one
  • An unknown URL gives JSON 404
  • An unexpected exception gives JSON 500 without the exception text, and the text is in the log
  • A request with another Host header (DNS rebinding) is refused
  • Every request reaches its route with the development user set
README
  • A short "Running the app" section: the new .env values (DEV_USERNAME, APP_PORT), py -m backend.main, and a clear note that there is no real login until M4

Where

backend/main.py, backend/controller/__init__.py, backend/controller/app_controller.py, tests/controller/test_app_controller.py

Done when

  • py -m backend.main starts the app; http://127.0.0.1:5000/api/health answers ok
  • With MySQL stopped, start-up fails with a clear message (or health reports unavailable), not a traceback
  • All controller tests pass without a database

Depends on

  • #44 Scan Session and Scan Manager (created in main.py)
  • #15, #16, #17 data access (created in main.py)
Dominant language
Python
Stars
1
Forks
1
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Bearkat-Professionals/Software-Engineering-Project

All issues in Bearkat-Professionals/Software-Engineering-Project

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.