Abstract
A Flask complaint-management web application covering the full complaint lifecycle: user authentication, complaint submission with optional media, filterable listings, status transitions, and administrative management of users and departments. The interesting part is treating the app as a stateful workflow rather than a set of isolated endpoints.
1. What This Is
I built this as a workflow-oriented Flask application for submitting and managing complaints. It covers both the user side (authenticate, submit, review) and the administrative side (status management, user and department management), making it more representative of a real CRUD/business application than a single-form demo.
The repository contains the application code, forms, model and helper modules, routes, and a test database. Users authenticate, submit complaints with optional attached media, and review complaint information through searchable views. Administrative functions manage complaint statuses, user accounts, and department records.
2. How It Works
The complaint lifecycle moves through five sequential stages. Each stage depends on the previous one: you cannot submit without authentication, and status updates are gated behind the admin role.
| # | Stage | Input | Tool | Output |
|---|---|---|---|---|
| 01 | Authenticate | Credentials | Flask auth | Session with role context |
| 02 | Submit complaint | Text + optional media | Form validation | Persisted complaint record |
| 03 | List / filter | Query parameters | SQLAlchemy queries | Filterable complaint views |
| 04 | Update status | Admin action | Route + model update | Transitioned complaint |
| 05 | Admin management | User / dept records | Admin routes | Updated org structure |
3. Implementation Notes
3.1 Modular file structure
Application concerns are separated across route, form, model, and helper modules rather than kept in a single Flask file. This made later changes easier because form definitions, data handling, and routing logic are not tightly mixed.
3.2 Authentication and role context
Complaint actions are associated with authenticated application users. The authentication flow establishes the appropriate role context so that administrative endpoints (status updates, user/department management) are only reachable by authorized staff.
3.3 Form handling with optional media
Complaint submission forms support textual information plus optional attached media. Validation is handled at the form layer before data reaches the model, keeping the persistence layer clean.
4. Constraints
-
No automated test suite
A test database ships with the repo, but no pytest or similar framework is described. Auth flows, complaint CRUD, and status transitions are unverified by code.
-
No deployment or CI configuration
The project assumes the Flask development server. There is no Dockerfile, Gunicorn config, or CI pipeline, so it is not production-ready as-is.
-
Security hardening is implicit
CSRF protection, rate limiting, and input sanitization beyond form validation are not explicitly documented. The auth model is functional but not hardened for adversarial input.
-
No pagination or search indexing
Complaint listings are filterable but there is no mention of pagination or full-text search, so the views will degrade as the complaint table grows.
5. Next
- a. Add a pytest suite covering authentication flows, complaint CRUD operations, and status transition edge cases.
- b. Add a Dockerfile with Gunicorn and a minimal CI pipeline (lint + test) so the project can be deployed beyond the dev server.
- c. Add pagination and full-text search to complaint listings, plus an audit log for every status transition.
— end of report —