How kaifhoda1/redflagscans works
RedFlagScans is a small, single-service Flask application with a very clear request/response pipeline: a user submits job-offer text or an uploaded document, the server analyzes it immediately, and the result is rendered back in the browser. There is no separate backend API service, database, queue, or background worker in this repo.
The repo has three core code areas:
• app.py: the HTTP application entry point and route layer
• analyzer.py: the scam-detection engine
• templates/index.html: the browser UI
The front end is server-rendered HTML rather than a SPA. The index page is the main interaction surface where a user pastes text or uploads a file. The browser submits the input to Flask, and Flask returns a page containing the risk score and detailed flags.
app.py is the orchestration boundary. It receives the request, validates the submitted content, dispatches text or file content into the analyzer, and prepares the response for the template. Based on the README, this layer also enforces operational constraints such as file-type/size checks and rate limiting.
analyzer.py is the main business-logic subsystem. It implements a rule-based detection engine that looks for scam patterns such as payment requests, urgency tactics, vague promises, suspicious contact methods, personal-email usage, and phishing language. It computes a capped risk score from matched patterns and returns an explanation of what triggered the score.
The data flow is linear and synchronous:
1. User enters text or uploads a document.
2. Flask accepts the request in app.py.
3. Uploaded documents are extracted into text, likely using PDF/DOCX parsing libraries noted in the README.
4. The extracted or pasted text is passed to analyzer.py.
5. The analyzer returns structured findings plus a 0–100 score.
6. Flask renders the result into index.html.
Document handling is an important architectural boundary. The app supports both plain text input and file input, so the server must normalize several input forms into a common text representation before analysis. This is where PDF/DOCX parsing sits, and where temporary-file handling and cleanup likely happen.
The scoring model is rule-based rather than ML-based. That means the analyzer is deterministic, explainable, and easy to extend by adding or tuning patterns. The architecture is centered on explainability: every risk score should map back to specific matched red flags.
There is no persistent user data layer in the current design. The README explicitly says no accounts, no storage, and deleted uploads after analysis. So the architecture should be drawn as stateless per-request processing with no database box.
Security and abuse-control are cross-cutting concerns around the Flask layer, not separate subsystems. The README indicates input sanitization, file validation, HTTPS enforcement in production, and rate limiting. These controls sit before or alongside the analyzer to protect the parsing and scoring path.
From a deployment perspective, the repo is a conventional Python web app. It runs locally with python3 app.py, which implies the Flask development server is the local entry point, while production deployment is externalized to a platform such as Render behind HTTPS.
For an architecture diagram, the most accurate shape is:
• Browser/UI on one side
• Flask app as the central request handler
• Analyzer as the internal decision engine
• Document parsers as an input-normalization step feeding the analyzer
• Rendered HTML response going back to the browser
• No database, queue, auth service, or long-lived storage in the core flow
Main entry points: analyzer.py Analyzer · app.py Routes · index.html Index Page
Components 9
Client
Browser-side interaction surface
- Browser · User enters job-offer text or uploads a document
- Index Page · Server-rendered form and results page
templates/index.html
Flask Service
Single synchronous web application
- Routes · HTTP request handling, validation, and response orchestration
app.py - Input Checks · File-type, size, sanitization, and rate-limit enforcement
app.py - Result Render · Injects findings into the template for browser display
app.py
Detection Engine
Rule-based scam analysis and document normalization
- Doc Normalizer · Converts uploaded PDFs or DOCX files into text
app.py - Analyzer · Main scam-detection logic and scoring
analyzer.py - Red-Flag Rules · Matches payment requests, urgency, vague promises, phishing language, and suspicious contacts
analyzer.py - Risk Score · Capped 0-100 score with explainable triggers
analyzer.py
Connections 13
- Browser → Index Page: loads form · The browser opens the server-rendered index page
- Index Page → Browser: shows UI · The page provides text entry and file upload controls
- Browser → Routes: submits input · User posts pasted text or an uploaded document
- Routes → Input Checks: validates · Flask enforces request and upload constraints before analysis
- Input Checks → Doc Normalizer: accepts file · Uploaded documents are normalized into plain text
- Input Checks → Analyzer: accepts text · Plain text submissions go directly to analysis
- Doc Normalizer → Analyzer: extracts text · Parsed document content is passed into the detection engine
- Analyzer → Red-Flag Rules: applies rules · The engine checks the text against scam indicators
- Red-Flag Rules → Risk Score: contributes matches · Matched patterns accumulate into a bounded risk score
- Analyzer → Risk Score: returns findings · The analyzer returns structured explanations and the final score
- Risk Score → Result Render: feeds result · Score and flags are prepared for the template context
- Routes → Result Render: renders page · Flask returns the updated HTML response
- Result Render → Browser: displays result · The browser shows the risk score and detailed red flags