# daelon711/inbox-shield-monver architecture

> Architecture diagram of the GitHub repository daelon711/inbox-shield-monver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daelon711/inbox-shield-monver
- Repository: https://github.com/daelon711/inbox-shield-monver

## Overview

Inbox Shield is a Flask email-screening and student-support application. Lecturers process read-only Gmail messages through a fixed filter → student lookup → FAQ drafting workflow, then review drafts without sending them; students use a separate public-document chatbot. The graph also shows retrieval, provider abstraction, validation and permission controls, and in-memory draft state. Relationships follow the README and shown source references; several UI and integration details are documented but their implementation was not sampled.

Main entry points: [`app/orchestrator.py`](https://github.com/daelon711/inbox-shield-monver/blob/main/app/orchestrator.py) (Email orchestrator), [`server.py`](https://github.com/daelon711/inbox-shield-monver/blob/main/server.py) (Flask routes), [`app/llm/factory.py`](https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/factory.py) (Provider factory), [`app/llm/base.py`](https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/base.py) (LLM interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and users"]
  node_server["Flask routes<br/>[server.py]"]
  node_lecturer_ui["Lecturer page<br/>[lecturer.html]"]
  node_chat_ui["Student chat page<br/>[chat.html]"]
end

subgraph group_email["Email workflow"]
  node_mail_reader["Read-only mail reader<br/>[gmail_reader.py]"]
  node_orchestrator["Email orchestrator<br/>[orchestrator.py]"]
  node_lookup_tool["Verified student lookup<br/>[tools.py]"]
end

subgraph group_agents["Agents and models"]
  node_filter["Email filter<br/>[agent.py]"]
  node_lookup_agent["Student lookup agent<br/>[agent.py]"]
  node_responder["FAQ responder<br/>[agent.py]"]
  node_chatbot["Support chatbot<br/>[agent.py]"]
  node_llm["LLM interface<br/>[base.py]"]
  node_llm_factory["Provider factory<br/>[factory.py]"]
  node_llm_mock["Mock provider<br/>[mock.py]"]
  node_llm_ollama["Ollama provider<br/>[ollama.py]"]
  node_llm_cyberlab["Cyberlab placeholder<br/>[cyberlab.py]"]
end

subgraph group_security["Security controls"]
  node_schemas["Data contracts<br/>[schemas.py]"]
  node_guards["Validation and release gates<br/>[guards.py]"]
  node_permissions["Role and tool policy<br/>[permissions.py]"]
  node_audit["Security audit log<br/>[audit.py]"]
end

subgraph group_data["Knowledge and state"]
  node_retriever["Document retrieval<br/>[retriever.py]"]
  node_knowledge["Course documents<br/>[knowledge.json]"]
  node_students_db["Student records<br/>[students.json]"]
  node_draft_store[("Draft store<br/>[data_store.py]")]
end

node_lecturer(("Lecturer"))
node_student(("Student"))
node_gmail["Gmail IMAP"]

node_lecturer -->|"reviews inbox"| node_lecturer_ui
node_lecturer_ui -->|"uses routes"| node_server
node_student -->|"asks questions"| node_chat_ui
node_chat_ui -->|"uses chat API"| node_server
node_server -->|"fetches mail"| node_mail_reader
node_mail_reader -->|"reads inbox"| node_gmail
node_server -->|"processes emails"| node_orchestrator
node_orchestrator -->|"validates inputs and outputs"| node_guards
node_orchestrator -->|"classifies email"| node_filter
node_orchestrator -->|"proposes lookup"| node_lookup_agent
node_orchestrator -->|"runs authorized lookup"| node_lookup_tool
node_lookup_tool -->|"checks student record"| node_students_db
node_orchestrator -->|"drafts FAQ reply"| node_responder
node_orchestrator -->|"retrieves FAQ context"| node_retriever
node_retriever -->|"ranks documents"| node_knowledge
node_orchestrator -->|"checks agent and tool access"| node_permissions
node_orchestrator -->|"saves approved-tool draft"| node_draft_store
node_server -->|"loads and decides drafts"| node_draft_store
node_server -->|"authorizes chat and documents"| node_permissions
node_server -->|"retrieves chat context"| node_retriever
node_server -->|"answers student"| node_chatbot
node_filter -->|"generates classification"| node_llm
node_lookup_agent -->|"generates proposal"| node_llm
node_responder -->|"generates draft"| node_llm
node_chatbot -->|"generates answer"| node_llm
node_server -->|"creates provider"| node_llm_factory
node_llm_factory -->|"selects provider"| node_llm_mock
node_llm_factory -->|"selects provider"| node_llm_ollama
node_llm_factory -->|"selects provider"| node_llm_cyberlab
node_guards -->|"validates contracts"| node_schemas
node_server -->|"records route outcomes"| node_audit
node_orchestrator -->|"records pipeline events"| node_audit

click node_server "https://github.com/daelon711/inbox-shield-monver/blob/main/server.py"
click node_lecturer_ui "https://github.com/daelon711/inbox-shield-monver/blob/main/templates/lecturer.html"
click node_chat_ui "https://github.com/daelon711/inbox-shield-monver/blob/main/templates/chat.html"
click node_mail_reader "https://github.com/daelon711/inbox-shield-monver/blob/main/app/mail/gmail_reader.py"
click node_orchestrator "https://github.com/daelon711/inbox-shield-monver/blob/main/app/orchestrator.py"
click node_filter "https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/filter/agent.py"
click node_lookup_agent "https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/lookup/agent.py"
click node_lookup_tool "https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/lookup/tools.py"
click node_responder "https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/responder/agent.py"
click node_chatbot "https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/chatbot/agent.py"
click node_llm "https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/base.py"
click node_llm_factory "https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/factory.py"
click node_llm_mock "https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/mock.py"
click node_llm_ollama "https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/ollama.py"
click node_llm_cyberlab "https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/cyberlab.py"
click node_retriever "https://github.com/daelon711/inbox-shield-monver/blob/main/app/rag/retriever.py"
click node_knowledge "https://github.com/daelon711/inbox-shield-monver/blob/main/data/knowledge.json"
click node_students_db "https://github.com/daelon711/inbox-shield-monver/blob/main/data/students.json"
click node_draft_store "https://github.com/daelon711/inbox-shield-monver/blob/main/app/services/data_store.py"
click node_schemas "https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/schemas.py"
click node_guards "https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/guards.py"
click node_permissions "https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/permissions.py"
click node_audit "https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/audit.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_server,node_lecturer_ui,node_chat_ui toneBlue
class node_mail_reader,node_orchestrator,node_lookup_tool toneAmber
class node_filter,node_lookup_agent,node_responder,node_chatbot,node_llm,node_llm_factory,node_llm_mock,node_llm_ollama,node_llm_cyberlab toneMint
class node_schemas,node_guards,node_permissions,node_audit toneRose
class node_retriever,node_knowledge,node_students_db,node_draft_store,node_lecturer,node_student,node_gmail toneIndigo
```

## Components

### Web and users

- [Flask routes](https://github.com/daelon711/inbox-shield-monver/blob/main/server.py): `server.py`
- [Lecturer page](https://github.com/daelon711/inbox-shield-monver/blob/main/templates/lecturer.html): `templates/lecturer.html`
- [Student chat page](https://github.com/daelon711/inbox-shield-monver/blob/main/templates/chat.html): `templates/chat.html`

### Email workflow

- [Read-only mail reader](https://github.com/daelon711/inbox-shield-monver/blob/main/app/mail/gmail_reader.py): `app/mail/gmail_reader.py`
- [Email orchestrator](https://github.com/daelon711/inbox-shield-monver/blob/main/app/orchestrator.py): `app/orchestrator.py`
- [Verified student lookup](https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/lookup/tools.py): `app/agents/lookup/tools.py`

### Agents and models

- [Email filter](https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/filter/agent.py): `app/agents/filter/agent.py`
- [Student lookup agent](https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/lookup/agent.py): `app/agents/lookup/agent.py`
- [FAQ responder](https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/responder/agent.py): `app/agents/responder/agent.py`
- [Support chatbot](https://github.com/daelon711/inbox-shield-monver/blob/main/app/agents/chatbot/agent.py): `app/agents/chatbot/agent.py`
- [LLM interface](https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/base.py): `app/llm/base.py`
- [Provider factory](https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/factory.py): `app/llm/factory.py`
- [Mock provider](https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/mock.py): `app/llm/mock.py`
- [Ollama provider](https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/ollama.py): `app/llm/ollama.py`
- [Cyberlab placeholder](https://github.com/daelon711/inbox-shield-monver/blob/main/app/llm/cyberlab.py): `app/llm/cyberlab.py`

### Security controls

- [Data contracts](https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/schemas.py): `app/security/schemas.py`
- [Validation and release gates](https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/guards.py): `app/security/guards.py`
- [Role and tool policy](https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/permissions.py): `app/security/permissions.py`
- [Security audit log](https://github.com/daelon711/inbox-shield-monver/blob/main/app/security/audit.py): `app/security/audit.py`

### Knowledge and state

- [Document retrieval](https://github.com/daelon711/inbox-shield-monver/blob/main/app/rag/retriever.py): `app/rag/retriever.py`
- [Course documents](https://github.com/daelon711/inbox-shield-monver/blob/main/data/knowledge.json): `data/knowledge.json`
- [Student records](https://github.com/daelon711/inbox-shield-monver/blob/main/data/students.json): `data/students.json`
- [Draft store](https://github.com/daelon711/inbox-shield-monver/blob/main/app/services/data_store.py): `app/services/data_store.py`

### Other components

- **Lecturer**
- **Student**
- **Gmail IMAP**

## Connections

- Lecturer → Lecturer page: reviews inbox (evidence: `README.md`)
- Lecturer page → Flask routes: uses routes (evidence: `README.md`)
- Student → Student chat page: asks questions (evidence: `README.md`)
- Student chat page → Flask routes: uses chat API (evidence: `README.md`)
- Flask routes → Read-only mail reader: fetches mail (evidence: `server.py`)
- Read-only mail reader → Gmail IMAP: reads inbox (evidence: `README.md`)
- Flask routes → Email orchestrator: processes emails (evidence: `server.py`)
- Email orchestrator → Validation and release gates: validates inputs and outputs (evidence: `app/orchestrator.py`)
- Email orchestrator → Email filter: classifies email (evidence: `app/orchestrator.py`)
- Email orchestrator → Student lookup agent: proposes lookup (evidence: `app/orchestrator.py`)
- Email orchestrator → Verified student lookup: runs authorized lookup (evidence: `app/orchestrator.py`)
- Verified student lookup → Student records: checks student record (evidence: `README.md`)
- Email orchestrator → FAQ responder: drafts FAQ reply (evidence: `app/orchestrator.py`)
- Email orchestrator → Document retrieval: retrieves FAQ context (evidence: `app/orchestrator.py`)
- Document retrieval → Course documents: ranks documents (evidence: `README.md`)
- Email orchestrator → Role and tool policy: checks agent and tool access (evidence: `app/orchestrator.py`)
- Email orchestrator → Draft store: saves approved-tool draft (evidence: `app/orchestrator.py`)
- Flask routes → Draft store: loads and decides drafts (evidence: `server.py`)
- Flask routes → Role and tool policy: authorizes chat and documents (evidence: `server.py`)
- Flask routes → Document retrieval: retrieves chat context (evidence: `server.py`)
- Flask routes → Support chatbot: answers student (evidence: `server.py`)
- Email filter → LLM interface: generates classification (evidence: `app/agents/filter/agent.py`)
- Student lookup agent → LLM interface: generates proposal (evidence: `app/agents/lookup/agent.py`)
- FAQ responder → LLM interface: generates draft (evidence: `app/agents/responder/agent.py`)
- Support chatbot → LLM interface: generates answer (evidence: `app/agents/chatbot/agent.py`)
- Flask routes → Provider factory: creates provider (evidence: `server.py`)
- Provider factory → Mock provider: selects provider (evidence: `app/llm/factory.py`)
- Provider factory → Ollama provider: selects provider (evidence: `app/llm/factory.py`)
- Provider factory → Cyberlab placeholder: selects provider (evidence: `app/llm/factory.py`)
- Validation and release gates → Data contracts: validates contracts (evidence: `app/security/guards.py`)
- Flask routes → Security audit log: records route outcomes (evidence: `server.py`)
- Email orchestrator → Security audit log: records pipeline events (evidence: `app/orchestrator.py`)