# faizan-devs/github-poc architecture

> Architecture diagram of the GitHub repository faizan-devs/github-poc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faizan-devs/github-poc
- Repository: https://github.com/faizan-devs/github-poc

## Overview

1. **What this repository is**
   - This is a small Node.js/TypeScript proof of concept for a **local agent runner**, not a typical web service.
   - Its purpose is to let an OpenAI-powered agent answer natural-language requests about a user’s GitHub account through **Corsair-managed GitHub access**.

2. **Main architectural shape**
   - The system has three core layers:
     - a **prompt/agent layer** in `src/server/agent.ts`
     - a **Corsair integration layer** in `src/server/corsair.ts`
     - a **local persistence layer** using SQLite, initialized by `migration.sql`
   - External dependencies are the **OpenAI API** and **GitHub**, with Corsair acting as the bridge for authenticated GitHub operations.

3. **Primary execution flow**
   - A user runs the agent from the command line.
   - The agent receives a natural-language request such as “List my GitHub repositories with the most open issues.”
   - The OpenAI Agents SDK reasons over the request and decides when to call tools.
   - Those tools are backed by Corsair, which performs GitHub actions using the user’s connected GitHub credentials.

4. **Agent runtime boundary**
   - `src/server/agent.ts` is the main runtime entrypoint.
   - It likely wires together the OpenAI Agents SDK, prompt handling, and the available tools.
   - This repo does not appear to expose an HTTP API; the interaction model is local execution from the terminal.

5. **Corsair integration boundary**
   - `src/server/corsair.ts` is the abstraction layer for Corsair-specific setup and access.
   - This is the key seam between the agent and GitHub: the agent should not talk to GitHub directly.
   - Instead, GitHub calls are delegated to Corsair, which manages authenticated SaaS integration details.

6. **Persistence and state**
   - `migration.sql` initializes the SQLite database used by Corsair, producing `corsair.db`.
   - The database is part of the integration state, not the main application domain logic.
   - From an architecture standpoint, SQLite is the local backing store for credential/integration metadata and related Corsair state.

7. **External systems**
   - **OpenAI** provides reasoning and tool-calling through the Agents SDK.
   - **GitHub** is the target SaaS being queried.
   - **Corsair** sits in the middle as the authenticated integration layer, so the app avoids writing custom GitHub API wrappers.

8. **Configuration and secrets**
   - The app depends on environment configuration for runtime access:
     - `OPENAI_API_KEY` for OpenAI
     - `CORSAIR_KEK` for Corsair
     - `GITHUB_TOKEN` to connect GitHub through Corsair setup
   - These are operational inputs, not application data, and should be shown as external configuration in a diagram.

9. **Setup-time data flow**
   - Before the agent can answer GitHub questions, the local SQLite DB is initialized from `migration.sql`.
   - Then Corsair is configured to connect the user’s GitHub account using the token.
   - After this setup, the agent can query GitHub data indirectly through Corsair.

10. **Testing / interactive use**
   - `src/test/interact.ts` suggests a lightweight manual test or interaction harness.
   - This is likely for experimenting with prompts and tool behavior rather than automated service orchestration.
   - It is a secondary entrypoint, useful for verifying agent behavior end-to-end.

11. **Key boundary to capture in an architecture diagram**
   - The most important boundary is between:
     - **agent reasoning** and
     - **authenticated GitHub access**
   - That boundary is mediated by Corsair, with SQLite supporting the integration state and OpenAI handling the reasoning.

12. **What is not in the architecture**
   - There is no evidence of a frontend, REST API, queue, job worker, or cloud deployment layer in this repo.
   - The architecture is intentionally minimal: local CLI execution, agent orchestration, integration bridge, and local SQLite state.

13. **Repo structure summary**
   - `src/server/agent.ts` = agent entrypoint and orchestration
   - `src/server/corsair.ts` = Corsair/GitHub integration layer
   - `src/test/interact.ts` = interactive test harness
   - `migration.sql` = SQLite schema/bootstrap for Corsair state

14. **One-sentence architecture summary**
   - This repository is a local TypeScript agent that uses OpenAI for reasoning and Corsair for authenticated GitHub tool access, with SQLite providing the integration state.

Main entry points: [`src/server/corsair.ts`](https://github.com/faizan-devs/github-poc/blob/main/src/server/corsair.ts) (Corsair setup), [`src/server/agent.ts`](https://github.com/faizan-devs/github-poc/blob/main/src/server/agent.ts) (Agent loop), [`src/test/interact.ts`](https://github.com/faizan-devs/github-poc/blob/main/src/test/interact.ts) (Interact harness), [`migration.sql`](https://github.com/faizan-devs/github-poc/blob/main/migration.sql) (Migration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_agent_entry["Agent entry<br/>cli entrypoint<br/>[agent.ts]"]
  node_agent_loop(("Agent loop<br/>orchestration<br/>[agent.ts]"))
  node_interact_harness["Interact harness<br/>manual test<br/>[interact.ts]"]
end

subgraph group_integration["Integration"]
  node_tool_bridge["Tool bridge<br/>tool adapter<br/>[agent.ts]"]
  node_corsair_setup["Corsair setup<br/>integration layer<br/>[corsair.ts]"]
  node_github_ops["GitHub ops<br/>saas adapter<br/>[corsair.ts]"]
end

subgraph group_state["State"]
  node_sqlite_db[("SQLite DB<br/>local state")]
  node_migration["Migration<br/>schema bootstrap<br/>[migration.sql]"]
end

subgraph group_external["External"]
  node_openai_api(("OpenAI API<br/>reasoning service"))
  node_github(("GitHub<br/>target saas"))
  node_env_config{{"Env config<br/>runtime config"}}
end

node_agent_entry -->|"starts"| node_agent_loop
node_agent_loop -->|"reasons with"| node_openai_api
node_agent_loop -->|"calls tools"| node_tool_bridge
node_tool_bridge -->|"delegates to"| node_corsair_setup
node_corsair_setup -->|"uses state"| node_sqlite_db
node_migration -->|"creates"| node_sqlite_db
node_corsair_setup -->|"configures"| node_github_ops
node_github_ops -->|"acts on"| node_github
node_agent_entry -->|"reads config"| node_env_config
node_corsair_setup -->|"reads config"| node_env_config
node_interact_harness -->|"exercises"| node_agent_loop

click node_agent_entry "https://github.com/faizan-devs/github-poc/blob/main/src/server/agent.ts"
click node_agent_loop "https://github.com/faizan-devs/github-poc/blob/main/src/server/agent.ts"
click node_tool_bridge "https://github.com/faizan-devs/github-poc/blob/main/src/server/agent.ts"
click node_corsair_setup "https://github.com/faizan-devs/github-poc/blob/main/src/server/corsair.ts"
click node_github_ops "https://github.com/faizan-devs/github-poc/blob/main/src/server/corsair.ts"
click node_migration "https://github.com/faizan-devs/github-poc/blob/main/migration.sql"
click node_interact_harness "https://github.com/faizan-devs/github-poc/blob/main/src/test/interact.ts"

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_agent_entry,node_agent_loop,node_interact_harness toneBlue
class node_tool_bridge,node_corsair_setup,node_github_ops toneAmber
class node_sqlite_db,node_migration toneMint
class node_openai_api,node_github,node_env_config toneRose
```

## Components

### Runtime

Local agent execution and interactive harness

- [Agent entry](https://github.com/faizan-devs/github-poc/blob/main/src/server/agent.ts): cli entrypoint · Main local runtime that starts the agent from the terminal · `src/server/agent.ts`
- [Agent loop](https://github.com/faizan-devs/github-poc/blob/main/src/server/agent.ts): orchestration · Coordinates prompt handling, reasoning, and tool invocation · `src/server/agent.ts`
- [Interact harness](https://github.com/faizan-devs/github-poc/blob/main/src/test/interact.ts): manual test · Secondary entrypoint for interactive prompt and tool testing · `src/test/interact.ts`

### Integration

Corsair-mediated GitHub access

- [Tool bridge](https://github.com/faizan-devs/github-poc/blob/main/src/server/agent.ts): tool adapter · Exposes agent tools that delegate GitHub work through Corsair · `src/server/agent.ts`
- [Corsair setup](https://github.com/faizan-devs/github-poc/blob/main/src/server/corsair.ts): integration layer · Initializes and configures Corsair access for authenticated GitHub operations · `src/server/corsair.ts`
- [GitHub ops](https://github.com/faizan-devs/github-poc/blob/main/src/server/corsair.ts): saas adapter · Executes GitHub-related actions through Corsair-managed credentials · `src/server/corsair.ts`

### State

Local SQLite persistence and bootstrap

- **SQLite DB**: local state · Local backing store for Corsair integration metadata and state
- [Migration](https://github.com/faizan-devs/github-poc/blob/main/migration.sql): schema bootstrap · Initializes the SQLite database schema used by Corsair · `migration.sql`

### External

Third-party services and runtime configuration

- **OpenAI API**: reasoning service · Provides model reasoning and tool-calling for the agent
- **GitHub**: target saas · User GitHub account and repositories queried by the agent
- **Env config**: runtime config · Operational inputs such as OPENAI_API_KEY, CORSAIR_KEK, and GITHUB_TOKEN

## Connections

- Agent entry → Agent loop: starts · CLI execution enters the agent orchestration loop
- Agent loop → OpenAI API: reasons with · The agent uses OpenAI for planning and tool selection
- Agent loop → Tool bridge: calls tools · Reasoning results in tool invocations through the agent tool layer
- Tool bridge → Corsair setup: delegates to · Tools hand off GitHub work to the Corsair integration boundary
- Corsair setup → SQLite DB: uses state · Corsair reads and writes local integration state in SQLite
- Migration → SQLite DB: creates · Schema bootstrap initializes the local database
- Corsair setup → GitHub ops: configures · Corsair setup prepares the authenticated GitHub operation layer
- GitHub ops → GitHub: acts on · Authenticated operations ultimately target GitHub
- Agent entry → Env config: reads config · Runtime configuration and secrets are loaded at startup
- Corsair setup → Env config: reads config · Corsair setup depends on integration credentials and keys
- Interact harness → Agent loop: exercises · Manual harness drives the same local agent flow for testing
