System Architecture

System Architecture

Envoy is designed as a modular, review-first autonomous job application agent that runs entirely on your local machine. Its architecture comprises three distinct services, each with a specific role and clear boundaries for interaction, ensuring a robust and maintainable system.

At a high level, the system operates with a unidirectional data flow:

Portal (React)  →  Agent (Python)  →  Tools (Node/Playwright)

This ensures that user actions initiated in the Portal are processed by the Agent, which then coordinates browser interactions via the Tools service. Data flows in one direction, simplifying state management and interaction patterns.

Core Services

Each service is independently responsible for a specific part of Envoy's functionality:

| Service | Stack | Responsibility | | :------ | :----------------------------- | :------------------------------------------------- | | Agent | Python 3.12, FastAPI, LangGraph | Orchestration, AI logic, persistence, HTTP API | | Tools | Node 20, Fastify, Playwright | Browser automation and HTML parsing. (Stateless) | | Portal | React 18, Vite, TypeScript | User interface for job review and interaction |

1. Agent

The Agent is the central intelligence and orchestrator of Envoy. Built with Python, FastAPI, and LangGraph, it manages all core business logic, AI interactions, and data persistence.

• Responsibilities:
  • Orchestration: Manages the entire job application lifecycle, from searching and preparing applications to human review and final submission.
  • Artificial Intelligence: Incorporates LLMs (via LangGraph) for tasks like evaluating job fit, generating cover letters, and conducting profile interviews.
  • Persistence: It is the only service that writes to the SQLite database, ensuring a single source of truth for application state, job listings, and user profiles.
  • API Provider: Exposes a RESTful API that the Portal interacts with to initiate actions and retrieve data.

2. Tools

The Tools service acts as Envoy's "eyes and hands" in the web browser. Implemented with Node.js, Fastify, and Playwright, it provides a set of browser automation and parsing capabilities.

• Responsibilities:
  • Browser Automation: Navigates job boards (e.g., SEEK, Indeed, LinkedIn), fills out application forms, and interacts with web elements.
  • HTML Parsing: Extracts structured data from web pages, such as job descriptions, company details, and application form fields.
• Key Characteristics:
  • Stateless: The Tools service maintains browser sessions in memory only; no data is persisted to disk by this service, meaning sessions are lost on restart.
  • Agent-Driven: It only responds to requests from the Agent and never initiates communication back to the Agent.

3. Portal

The Portal is the user-facing interface, built using React, Vite, and TypeScript. It provides a rich and interactive experience for users to review jobs, manage applications, and interact with the agent.

• Responsibilities:
  • User Interface: Displays job listings, application drafts, profile interview prompts, and allows users to make decisions (e.g., Review, Ignore, Approve, Edit).
  • Interaction Point: Enables users to initiate workflows (e.g., "Run Search," "Start Applying") and provide input (e.g., cover letter edits, interview answers).
• Key Characteristics:
  • Client-Side Application: Runs in the user's web browser, communicating exclusively with the Agent's API.
  • Separation of Concerns: The Portal is unaware of the Tools service's existence; all browser-related operations are abstracted behind the Agent.

Data Flow and Communication Principles

The architecture adheres to strict communication principles:

• Unidirectional Flow: The flow of control and data is strictly Portal → Agent → Tools.
• Agent as Mediator: The Agent acts as the sole intermediary between the Portal and the Tools service. The Portal never directly communicates with Tools.
• No Callback from Tools: The Tools service never calls back to the Agent. It executes tasks and returns results to the Agent, maintaining a simple request/response pattern.
• Centralized Persistence: Only the Agent service is authorized to write to the underlying SQLite database, ensuring data integrity and consistency.
• Ephemeral Browser State: Browser sessions and any intermediate data within the Tools service are held in memory only, making the Tools service easy to restart and scale (though for Envoy, it's a single instance).

For a detailed visual representation of the application's step-by-step product flow, please refer to the docs/envoy-flow.md document.