# dineshkrishna9999/firsttoknow architecture

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

- Interactive diagram: https://gitdiagram.com/dineshkrishna9999/firsttoknow
- Repository: https://github.com/dineshkrishna9999/firsttoknow

## Overview

#### Purpose and Entry Points
FirstToKnow is a Python 3.11+ terminal application that tracks a developer’s dependencies, repositories, and topics; produces LLM-prioritized tech briefings; and guards new dependencies before git pushes. The executable entry path is `src/firsttoknow/__main__.py`, delegating command handling to the Typer CLI in `src/firsttoknow/cli.py`.

#### CLI Orchestration and Persistent State
The CLI exposes tracking, scanning, briefing, guard, hook-installation, and configuration commands. It is the main boundary between user input and internal workflows. User-selected model settings and tracked items are persisted under the user’s `~/.firsttoknow/` area through `src/firsttoknow/config.py`; shared domain records and report/severity types live in `src/firsttoknow/models.py`.

Paths: `src/firsttoknow/cli.py`, `src/firsttoknow/config.py`, `src/firsttoknow/models.py`.

#### Dependency Discovery and Tracking
`scan` discovers dependencies from supported project manifests, while explicit `track` commands add PyPI, npm, GitHub, or topic targets. Scanner output becomes tracked-item state, rather than directly invoking briefing services. This keeps local project inspection separate from remote intelligence gathering.

Paths: `src/firsttoknow/scanner.py`, `src/firsttoknow/cli.py`, `src/firsttoknow/models.py`.

#### Agent-Driven Briefing Pipeline
`brief` loads tracked state and runs an ADK-based agent. The agent receives briefing instructions and dynamically selects information-gathering tools; the application does not hardcode a fixed fetch sequence. LiteLLM provides model-provider abstraction, allowing OpenAI, Azure OpenAI, Gemini, Anthropic, or local Ollama models. The resulting synthesis is prioritized into critical, important, and FYI content.

Paths: `src/firsttoknow/agents/agent.py`, `src/firsttoknow/agents/instructions/briefing.py`, `src/firsttoknow/agents/_tools.py`.

#### External Intelligence and Security Boundary
Agent tools make live calls to PyPI, npm, GitHub, Hacker News, Dev.to, Reddit, and OSV.dev. OSV is the vulnerability authority for CVE lookup; package registries and social/code platforms supply release, repository, and discussion context. Tool implementations are centralized, making remote API behavior a clear boundary from agent reasoning.

Paths: `src/firsttoknow/agents/_tools.py`, `src/firsttoknow/agents/agent.py`.

#### Guard and Git Hook Workflow
The guard examines git diffs for newly introduced dependencies, then evaluates OSV vulnerabilities, license changes, and probable typosquats. An optional LLM review extends this flow to source diffs. Hook support installs/invokes the guard as a pre-push control point, so a risky dependency can be identified before code leaves the local repository.

Paths: `src/firsttoknow/guard.py`, `src/firsttoknow/hooks.py`, `src/firsttoknow/typosquat.py`.

#### Presentation Runtime
Rich terminal rendering handles progress feedback, formatted Markdown briefings, hyperlinks, status views, and guard-grade reports. It is downstream of both agent and guard workflows and should not own business decisions.

Paths: `src/firsttoknow/renderer.py`, `src/firsttoknow/cli.py`.

#### Runtime and Delivery
The runtime is packaged as a typed Python project under `src/firsttoknow/`, with dependencies and task definitions in `pyproject.toml` and `poe.toml`. Development is container-capable via `.devcontainer/`, while CI is defined in `.github/workflows/ci.yml`.

Main entry points: [`src/firsttoknow/cli.py`](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/cli.py) (Typer CLI), [`src/firsttoknow/agents/agent.py`](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/agent.py) (ADK briefing agent), [`src/firsttoknow/guard.py`](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/guard.py) (Dependency guard), [`src/firsttoknow/agents/_tools.py`](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/_tools.py) (Intelligence tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & State"]
  node_entry["Python entry point<br/>executable<br/>[__main__.py]"]
  node_cli_app["Typer CLI<br/>command orchestrator<br/>[cli.py]"]
  node_config[("User config &amp; tracked state<br/>persistence<br/>[config.py]")]
  node_models["Domain models<br/>shared types<br/>[models.py]"]
  node_scanner["Manifest scanner<br/>dependency discovery<br/>[scanner.py]"]
end

subgraph group_briefing["Briefing Pipeline"]
  node_agent{{"ADK briefing agent<br/>agent runtime<br/>[agent.py]"}}
  node_instructions["Briefing instructions<br/>agent prompt<br/>[briefing.py]"]
  node_tools["Intelligence tools<br/>remote API adapter<br/>[_tools.py]"]
  node_llm{{"LiteLLM providers<br/>model gateway"}}
  node_intel_sources(("Registries &amp; community sources<br/>external intelligence"))
end

subgraph group_guard["Pre-push Guard"]
  node_guard_engine["Dependency guard<br/>risk workflow<br/>[guard.py]"]
  node_typosquat["Typosquat detection<br/>risk analysis<br/>[typosquat.py]"]
  node_hooks["Git hook support<br/>pre-push integration<br/>[hooks.py]"]
  node_git_repo[("Local Git repository<br/>developer workspace")]
end

node_osv(("OSV.dev<br/>vulnerability authority"))
node_renderer["Rich renderer<br/>terminal presentation<br/>[renderer.py]"]

node_entry -->|"delegates"| node_cli_app
node_cli_app -->|"reads and writes"| node_config
node_cli_app -->|"uses"| node_models
node_cli_app -->|"runs scan"| node_scanner
node_scanner -->|"stores discovered targets"| node_config
node_cli_app -->|"runs brief"| node_agent
node_config -->|"loads tracked items and model settings"| node_agent
node_agent -->|"uses"| node_instructions
node_agent -->|"selects dynamically"| node_tools
node_agent -->|"synthesizes via"| node_llm
node_tools -->|"fetches context"| node_intel_sources
node_tools -->|"queries vulnerabilities"| node_osv
node_cli_app -->|"runs guard"| node_guard_engine
node_hooks -->|"invokes pre-push"| node_guard_engine
node_git_repo -->|"provides diffs"| node_guard_engine
node_guard_engine -->|"checks vulnerabilities"| node_osv
node_guard_engine -->|"checks package names"| node_typosquat
node_agent -->|"briefing output"| node_renderer
node_guard_engine -->|"guard report"| node_renderer
node_cli_app -->|"renders status"| node_renderer

click node_entry "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/__main__.py"
click node_cli_app "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/cli.py"
click node_config "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/config.py"
click node_models "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/models.py"
click node_scanner "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/scanner.py"
click node_agent "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/agent.py"
click node_instructions "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/instructions/briefing.py"
click node_tools "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/_tools.py"
click node_guard_engine "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/guard.py"
click node_typosquat "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/typosquat.py"
click node_hooks "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/hooks.py"
click node_renderer "https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/renderer.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_entry,node_cli_app,node_config,node_models,node_scanner toneBlue
class node_agent,node_instructions,node_tools,node_llm,node_intel_sources toneAmber
class node_guard_engine,node_typosquat,node_hooks,node_git_repo toneMint
class node_osv,node_renderer toneNeutral
```

## Components

### CLI & State

User-facing commands and persistent tracking state.

- [Python entry point](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/__main__.py): executable · `src/firsttoknow/__main__.py`
- [Typer CLI](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/cli.py): command orchestrator · `src/firsttoknow/cli.py`
- [User config & tracked state](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/config.py): persistence · Stores settings and tracked items under ~/.firsttoknow/. · `src/firsttoknow/config.py`
- [Domain models](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/models.py): shared types · Tracked-item, report, and severity records. · `src/firsttoknow/models.py`
- [Manifest scanner](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/scanner.py): dependency discovery · `src/firsttoknow/scanner.py`

### Briefing Pipeline

Agent-driven research and prioritized synthesis.

- [ADK briefing agent](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/agent.py): agent runtime · Dynamically selects research tools for each briefing. · `src/firsttoknow/agents/agent.py`
- [Briefing instructions](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/instructions/briefing.py): agent prompt · `src/firsttoknow/agents/instructions/briefing.py`
- [Intelligence tools](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/agents/_tools.py): remote API adapter · Centralizes live registry, code, discussion, and vulnerability calls. · `src/firsttoknow/agents/_tools.py`
- **LiteLLM providers**: model gateway · Routes to hosted or local language models.
- **Registries & community sources**: external intelligence · PyPI, npm, GitHub, Hacker News, Dev.to, and Reddit.

### Pre-push Guard

Dependency risk checks before code is pushed.

- [Dependency guard](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/guard.py): risk workflow · Checks newly introduced dependencies and optional source diffs. · `src/firsttoknow/guard.py`
- [Typosquat detection](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/typosquat.py): risk analysis · `src/firsttoknow/typosquat.py`
- [Git hook support](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/hooks.py): pre-push integration · Installs and invokes the guard at the pre-push control point. · `src/firsttoknow/hooks.py`
- **Local Git repository**: developer workspace

### Other components

- **OSV.dev**: vulnerability authority · CVE and vulnerability lookup source.
- [Rich renderer](https://github.com/dineshkrishna9999/firsttoknow/blob/main/src/firsttoknow/renderer.py): terminal presentation · Renders progress, briefings, status, and guard reports. · `src/firsttoknow/renderer.py`

## Connections

- Python entry point → Typer CLI: delegates
- Typer CLI → User config & tracked state: reads and writes
- Typer CLI → Domain models: uses
- Typer CLI → Manifest scanner: runs scan
- Manifest scanner → User config & tracked state: stores discovered targets
- Typer CLI → ADK briefing agent: runs brief
- User config & tracked state → ADK briefing agent: loads tracked items and model settings
- ADK briefing agent → Briefing instructions: uses
- ADK briefing agent → Intelligence tools: selects dynamically
- ADK briefing agent → LiteLLM providers: synthesizes via
- Intelligence tools → Registries & community sources: fetches context
- Intelligence tools → OSV.dev: queries vulnerabilities
- Typer CLI → Dependency guard: runs guard
- Git hook support → Dependency guard: invokes pre-push
- Local Git repository → Dependency guard: provides diffs
- Dependency guard → OSV.dev: checks vulnerabilities
- Dependency guard → Typosquat detection: checks package names
- ADK briefing agent → Rich renderer: briefing output
- Dependency guard → Rich renderer: guard report
- Typer CLI → Rich renderer: renders status