# kaifhoda1/redflagscans architecture

> Architecture diagram of the GitHub repository kaifhoda1/redflagscans, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaifhoda1/redflagscans
- Repository: https://github.com/kaifhoda1/redflagscans

## Overview

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`](https://github.com/kaifhoda1/redflagscans/blob/main/analyzer.py) (Analyzer), [`app.py`](https://github.com/kaifhoda1/redflagscans/blob/main/app.py) (Routes), [`templates/index.html`](https://github.com/kaifhoda1/redflagscans/blob/main/templates/index.html) (Index Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>ui client"))
  node_index_template["Index Page<br/>server template<br/>[index.html]"]
end

subgraph group_server["Flask Service"]
  node_http_routes["Routes<br/>Flask entrypoint<br/>[app.py]"]
  node_input_checks["Input Checks<br/>request guard<br/>[app.py]"]
  node_render_response["Result Render<br/>HTML response<br/>[app.py]"]
end

subgraph group_analysis["Detection Engine"]
  node_upload_normalizer["Doc Normalizer<br/>file intake<br/>[app.py]"]
  node_analyzer_engine{{"Analyzer<br/>rule engine<br/>[analyzer.py]"}}
  node_pattern_rules["Red-Flag Rules<br/>pattern set<br/>[analyzer.py]"]
  node_risk_score(("Risk Score<br/>scoring output<br/>[analyzer.py]"))
end

node_browser -->|"loads form"| node_index_template
node_index_template -->|"shows UI"| node_browser
node_browser -->|"submits input"| node_http_routes
node_http_routes -->|"validates"| node_input_checks
node_input_checks -->|"accepts file"| node_upload_normalizer
node_input_checks -->|"accepts text"| node_analyzer_engine
node_upload_normalizer -->|"extracts text"| node_analyzer_engine
node_analyzer_engine -->|"applies rules"| node_pattern_rules
node_pattern_rules -->|"contributes matches"| node_risk_score
node_analyzer_engine -->|"returns findings"| node_risk_score
node_risk_score -->|"feeds result"| node_render_response
node_http_routes -->|"renders page"| node_render_response
node_render_response -->|"displays result"| node_browser

click node_index_template "https://github.com/kaifhoda1/redflagscans/blob/main/templates/index.html"
click node_http_routes "https://github.com/kaifhoda1/redflagscans/blob/main/app.py"
click node_input_checks "https://github.com/kaifhoda1/redflagscans/blob/main/app.py"
click node_upload_normalizer "https://github.com/kaifhoda1/redflagscans/blob/main/app.py"
click node_analyzer_engine "https://github.com/kaifhoda1/redflagscans/blob/main/analyzer.py"
click node_pattern_rules "https://github.com/kaifhoda1/redflagscans/blob/main/analyzer.py"
click node_risk_score "https://github.com/kaifhoda1/redflagscans/blob/main/analyzer.py"
click node_render_response "https://github.com/kaifhoda1/redflagscans/blob/main/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_index_template toneBlue
class node_http_routes,node_input_checks,node_render_response toneAmber
class node_upload_normalizer,node_analyzer_engine,node_pattern_rules,node_risk_score toneMint
```

## Components

### Client

Browser-side interaction surface

- **Browser**: ui client · User enters job-offer text or uploads a document
- [Index Page](https://github.com/kaifhoda1/redflagscans/blob/main/templates/index.html): server template · Server-rendered form and results page · `templates/index.html`

### Flask Service

Single synchronous web application

- [Routes](https://github.com/kaifhoda1/redflagscans/blob/main/app.py): Flask entrypoint · HTTP request handling, validation, and response orchestration · `app.py`
- [Input Checks](https://github.com/kaifhoda1/redflagscans/blob/main/app.py): request guard · File-type, size, sanitization, and rate-limit enforcement · `app.py`
- [Result Render](https://github.com/kaifhoda1/redflagscans/blob/main/app.py): HTML response · Injects findings into the template for browser display · `app.py`

### Detection Engine

Rule-based scam analysis and document normalization

- [Doc Normalizer](https://github.com/kaifhoda1/redflagscans/blob/main/app.py): file intake · Converts uploaded PDFs or DOCX files into text · `app.py`
- [Analyzer](https://github.com/kaifhoda1/redflagscans/blob/main/analyzer.py): rule engine · Main scam-detection logic and scoring · `analyzer.py`
- [Red-Flag Rules](https://github.com/kaifhoda1/redflagscans/blob/main/analyzer.py): pattern set · Matches payment requests, urgency, vague promises, phishing language, and suspicious contacts · `analyzer.py`
- [Risk Score](https://github.com/kaifhoda1/redflagscans/blob/main/analyzer.py): scoring output · Capped 0-100 score with explainable triggers · `analyzer.py`

## Connections

- 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
