# raslmm/safebite architecture

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

- Interactive diagram: https://gitdiagram.com/raslmm/safebite
- Repository: https://github.com/raslmm/safebite

## Overview

SafeBite is a Streamlit app for checking packaged-food ingredient text against a user’s selected allergens. Users sign in, select or load an allergy profile, enter and review label text, then ask the agent to check it; the deterministic checker returns a risk assessment with evidence. Google model calls support the conversational interface, while MongoDB stores profiles and demo email accounts. The README also documents Google OIDC and a planned photo scanner; the scanner has no implemented runtime path. Edges reflect the excerpts, SOURCE INDEX references, or README; unsampled behavior is not inferred.

Main entry points: [`app.py`](https://github.com/raslmm/safebite/blob/main/app.py) (Streamlit app), [`safebite_agent/agent.py`](https://github.com/raslmm/safebite/blob/main/safebite_agent/agent.py) (Agent turn), [`safebite_agent/llm.py`](https://github.com/raslmm/safebite/blob/main/safebite_agent/llm.py) (Google model adapter), [`safebite_agent/tracing.py`](https://github.com/raslmm/safebite/blob/main/safebite_agent/tracing.py) (Request tracing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User application"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_label["Reviewed label<br/>[app.py]"]
  node_photo["Photo scanner &#40;planned&#41;<br/>[app.py]"]
end

subgraph group_identity["Identity and profiles"]
  node_google_oidc["Google OIDC"]
  node_email_auth["Email account auth<br/>[email_auth.py]"]
  node_profile_store[("Allergy profile store<br/>[profile_store.py]")]
end

subgraph group_screening["Screening and agent"]
  node_agent["Agent turn<br/>[agent.py]"]
  node_tool_gateway["Tool dispatch<br/>[tools.py]"]
  node_checker["Allergen checker"]
  node_reference["EU allergen reference"]
  node_contracts["Typed contracts<br/>[schemas.py]"]
end

subgraph group_platform["Model and observability"]
  node_model_adapter["Google model adapter<br/>[llm.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_tracing["Request tracing<br/>[tracing.py]"]
end

node_user(("User"))
node_mongodb[("MongoDB")]
node_google_genai["Google GenAI"]
node_langfuse["Langfuse"]

node_user -->|"uses"| node_streamlit
node_streamlit -->|"authenticates"| node_email_auth
node_streamlit -.->|"signs in"| node_google_oidc
node_streamlit -->|"loads and saves"| node_profile_store
node_email_auth -->|"stores accounts"| node_mongodb
node_profile_store -->|"stores profiles"| node_mongodb
node_user -->|"enters text"| node_label
node_streamlit -->|"saves reviewed text"| node_label
node_streamlit -->|"asks"| node_agent
node_agent -->|"requests turn"| node_model_adapter
node_model_adapter -->|"calls"| node_google_genai
node_model_adapter -->|"reads settings"| node_config
node_agent -->|"dispatches calls"| node_tool_gateway
node_tool_gateway -->|"checks label"| node_checker
node_checker -->|"matches terms"| node_reference
node_streamlit -->|"shows catalog"| node_reference
node_streamlit -->|"builds label data"| node_contracts
node_agent -->|"uses contracts"| node_contracts
node_streamlit -->|"uses profile types"| node_contracts
node_model_adapter -->|"records calls"| node_tracing
node_tracing -->|"reads settings"| node_config
node_tracing -.->|"records traces"| node_langfuse
node_streamlit -->|"shows assessment"| node_user
node_user -.->|"requests scan"| node_photo

click node_streamlit "https://github.com/raslmm/safebite/blob/main/app.py"
click node_label "https://github.com/raslmm/safebite/blob/main/app.py"
click node_photo "https://github.com/raslmm/safebite/blob/main/app.py"
click node_email_auth "https://github.com/raslmm/safebite/blob/main/safebite_agent/email_auth.py"
click node_profile_store "https://github.com/raslmm/safebite/blob/main/safebite_agent/profile_store.py"
click node_agent "https://github.com/raslmm/safebite/blob/main/safebite_agent/agent.py"
click node_tool_gateway "https://github.com/raslmm/safebite/blob/main/safebite_agent/tools.py"
click node_checker "https://github.com/raslmm/safebite/blob/main/safebite_agent/allergen_checker.py"
click node_reference "https://github.com/raslmm/safebite/blob/main/safebite_agent/allergen_reference.py"
click node_contracts "https://github.com/raslmm/safebite/blob/main/safebite_agent/schemas.py"
click node_model_adapter "https://github.com/raslmm/safebite/blob/main/safebite_agent/llm.py"
click node_config "https://github.com/raslmm/safebite/blob/main/safebite_agent/config.py"
click node_tracing "https://github.com/raslmm/safebite/blob/main/safebite_agent/tracing.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_streamlit,node_label,node_photo,node_user toneBlue
class node_google_oidc,node_email_auth,node_profile_store,node_mongodb toneAmber
class node_agent,node_tool_gateway,node_checker,node_reference,node_contracts toneMint
class node_model_adapter,node_config,node_tracing toneRose
class node_google_genai,node_langfuse toneIndigo
```

## Components

### User application

- [Streamlit app](https://github.com/raslmm/safebite/blob/main/app.py): `app.py`
- [Reviewed label](https://github.com/raslmm/safebite/blob/main/app.py): `app.py`
- [Photo scanner (planned)](https://github.com/raslmm/safebite/blob/main/app.py): `app.py`

### Identity and profiles

- **Google OIDC**
- [Email account auth](https://github.com/raslmm/safebite/blob/main/safebite_agent/email_auth.py): `safebite_agent/email_auth.py`
- [Allergy profile store](https://github.com/raslmm/safebite/blob/main/safebite_agent/profile_store.py): `safebite_agent/profile_store.py`

### Screening and agent

- [Agent turn](https://github.com/raslmm/safebite/blob/main/safebite_agent/agent.py): `safebite_agent/agent.py`
- [Tool dispatch](https://github.com/raslmm/safebite/blob/main/safebite_agent/tools.py): `safebite_agent/tools.py`
- [Allergen checker](https://github.com/raslmm/safebite/blob/main/safebite_agent/allergen_checker.py): `safebite_agent/allergen_checker.py`
- [EU allergen reference](https://github.com/raslmm/safebite/blob/main/safebite_agent/allergen_reference.py): `safebite_agent/allergen_reference.py`
- [Typed contracts](https://github.com/raslmm/safebite/blob/main/safebite_agent/schemas.py): `safebite_agent/schemas.py`

### Model and observability

- [Google model adapter](https://github.com/raslmm/safebite/blob/main/safebite_agent/llm.py): `safebite_agent/llm.py`
- [Runtime settings](https://github.com/raslmm/safebite/blob/main/safebite_agent/config.py): `safebite_agent/config.py`
- [Request tracing](https://github.com/raslmm/safebite/blob/main/safebite_agent/tracing.py): `safebite_agent/tracing.py`

### Other components

- **User**
- **MongoDB**
- **Google GenAI**
- **Langfuse**

## Connections

- User → Streamlit app: uses (evidence: `README.md`)
- Streamlit app → Email account auth: authenticates (evidence: `app.py`)
- Streamlit app → Google OIDC: signs in (evidence: `README.md`)
- Streamlit app → Allergy profile store: loads and saves (evidence: `app.py`)
- Email account auth → MongoDB: stores accounts (evidence: `safebite_agent/email_auth.py`)
- Allergy profile store → MongoDB: stores profiles (evidence: `safebite_agent/profile_store.py`)
- User → Reviewed label: enters text (evidence: `app.py`)
- Streamlit app → Reviewed label: saves reviewed text (evidence: `app.py`)
- Streamlit app → Agent turn: asks (evidence: `app.py`)
- Agent turn → Google model adapter: requests turn (evidence: `safebite_agent/agent.py`)
- Google model adapter → Google GenAI: calls (evidence: `safebite_agent/llm.py`)
- Google model adapter → Runtime settings: reads settings (evidence: `safebite_agent/llm.py`)
- Agent turn → Tool dispatch: dispatches calls (evidence: `safebite_agent/agent.py`)
- Tool dispatch → Allergen checker: checks label (evidence: `safebite_agent/tools.py`)
- Allergen checker → EU allergen reference: matches terms (evidence: `safebite_agent/allergen_checker.py`)
- Streamlit app → EU allergen reference: shows catalog (evidence: `app.py`)
- Streamlit app → Typed contracts: builds label data (evidence: `app.py`)
- Agent turn → Typed contracts: uses contracts (evidence: `safebite_agent/agent.py`)
- Streamlit app → Typed contracts: uses profile types (evidence: `app.py`)
- Google model adapter → Request tracing: records calls (evidence: `safebite_agent/llm.py`)
- Request tracing → Runtime settings: reads settings (evidence: `safebite_agent/tracing.py`)
- Request tracing → Langfuse: records traces (evidence: `safebite_agent/tracing.py`)
- Streamlit app → User: shows assessment (evidence: `app.py`)
- User → Photo scanner (planned): requests scan (evidence: `README.md`)
