# pixjobs/pixjobs-adk-hackathon architecture

> Architecture diagram of the GitHub repository pixjobs/pixjobs-adk-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pixjobs/pixjobs-adk-hackathon
- Repository: https://github.com/pixjobs/pixjobs-adk-hackathon

## Overview

##### Project Type & Purpose
- WorkMatch is a backend‐centric, multi‐agent career guidance assistant built on the Python Agent Development Kit (ADK) and deployed as a Cloud Run service.
- Its core purpose is to orchestrate modular “agents” that collaborate—with real‐time listings and structured logic—to guide users through career exploration, job discovery, and upskilling.

##### File Structure Analysis
- Top‐level:
– .dockerignore, Docker/Git configs, LICENSE, README.md
– backend/ – contains the runnable service
- backend/
– workmatch/ – main Python package
– agent.py, prompt.py – entry-points for root agent orchestration
– sub_agents/ – each module implements a specialized agent (entry_level, advanced_pathways, title_variants, etc.)
– tools/ – reusable career_tools for job logic, queries, formatting
– utils/ – integrations (adzuna API helper, Firestore helper, tracing, env/secret management)

##### README Insights
- Multi‐agent orchestration: a single root agent routes to many sub-agents, each with a focused role.
- ADK best practices: uses TracedAgentTool and TracedFunctionTool for observability with Langfuse.
- Deploys on Google Cloud Run; uses Firestore for persistent storage; Adzuna API for job data; Secret Manager for credentials.
- Future: a React+TypeScript frontend is planned, but currently uses the ADK Web interface for local/dev.

a. Main Components
– User & ADK Web UI (or future React UI)
– Cloud Run service (HTTP/gRPC endpoint)
– Root Agent (workmatch_root_agent)
– Sub-Agents modules (entry_level_agent, career_guidance_agent, advanced_pathways_agent, etc.)
– Tools layer (career_tools)
– Utility integrations: Adzuna API client, Firestore helper, Secret Manager, Langfuse tracing
– Firestore Database (persistent job listings)
– External services: Adzuna REST API, Google Secret Manager, Langfuse observability

b. Relationships & Interactions
1. User → ADK Web UI (or React frontend) → HTTP Request → Cloud Run
2. Cloud Run endpoint instantiates Root Agent
3. Root Agent analyzes user input, invokes sub-agent modules
4. Sub-Agents call Tools (career_tools) for business logic or function tools (e.g. TracedFunctionTool)
5. Tools/util modules interact with:
- Adzuna API (live job data)
- Firestore helper (read/write cached listings)
- Secret Manager (API keys)
- Langfuse (trace logs)
6. Responses bubble back up: Tool → Sub-Agent → Root Agent → Cloud Run → UI → User

c. Architectural Patterns & Principles
- Modular multi-agent orchestration (separation of concerns per agent)
- Layered design: Agents → Tools → Utils → External
- Observability baked in via traced tools (Langfuse)
- Cloud-native deployment (stateless service + managed DB + secret store)

d. Key Technologies & Frameworks
- Python ADK (Agent Dev Kit)
- Google Cloud Run
- Firestore (NoSQL)
- Google Secret Manager
- Adzuna REST API
- Langfuse for tracing/logs

##### Detail & Fidelity
- Integrations (e.g., “FirestoreHelper: read/write listings”) to convey function.
- Orchestration pattern (Root → Sub-Agents → Tools) is unmistakable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Layer"
        User["User"]:::external
        UI["ADK Web UI / React UI"]:::external
        User -->|Interacts| UI
    end

    UI -->|HTTP Request| Prompt["HTTP/gRPC Endpoint<br/>(prompt.py)"]:::api
    click Prompt "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/prompt.py"

    subgraph "Orchestration Layer"
        CloudRun["Cloud Run Service"]:::cloud
        RootAgent["Root Agent<br/>(agent.py)"]:::agent
        click RootAgent "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/agent.py"
        Prompt --> CloudRun
        CloudRun --> RootAgent
    end

    subgraph "Agents Layer"
        EntryAgent["EntryLevelAgent<br/>(entry_level.py)"]:::agent
        click EntryAgent "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/sub_agents/entry_level.py"
        AdvAgent["AdvancedPathwaysAgent<br/>(advanced_pathways.py)"]:::agent
        click AdvAgent "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/sub_agents/advanced_pathways.py"
        InsightsAgent["ExpandedInsightsAgent<br/>(expanded_insights.py)"]:::agent
        click InsightsAgent "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/sub_agents/expanded_insights.py"
        TitleAgent["TitleVariantsAgent<br/>(title_variants.py)"]:::agent
        click TitleAgent "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/sub_agents/title_variants.py"
        RootAgent --> EntryAgent
        RootAgent --> AdvAgent
        RootAgent --> InsightsAgent
        RootAgent --> TitleAgent
    end

    subgraph "Tools & Utils Layer"
        Tools["CareerTools<br/>(career_tools.py)"]:::tool
        click Tools "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/tools/career_tools.py"
        AdzunaUtil["Adzuna API Client<br/>(adzuna.py)"]:::util
        click AdzunaUtil "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/utils/adzuna.py"
        FirestoreUtil["FirestoreHelper<br/>(firestore_helpers.py)"]:::util
        click FirestoreUtil "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/utils/firestore_helpers.py"
        EnvUtil["Env & Secret Manager Helper<br/>(env.py)"]:::util
        click EnvUtil "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/utils/env.py"
        TracedTools["Traced Function & Agent Tools<br/>(traced_tools.py)"]:::util
        click TracedTools "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/utils/traced_tools.py"
        TracingCfg["Tracing Config<br/>(tracing.py)"]:::util
        click TracingCfg "https://github.com/pixjobs/pixjobs-adk-hackathon/blob/main/backend/workmatch/utils/tracing.py"
        EntryAgent --> Tools
        AdvAgent --> Tools
        InsightsAgent --> Tools
        TitleAgent --> Tools
        Tools --> AdzunaUtil
        Tools --> FirestoreUtil
        Tools --> EnvUtil
        Tools --> TracedTools
        Tools --> TracingCfg
    end

    subgraph "External & Database"
        Firestore["Firestore Database"]:::db
        AdzunaAPI["Adzuna REST API"]:::external
        SecretMgr["Google Secret Manager"]:::external
        Langfuse["Langfuse Observability"]:::external
        FirestoreUtil --> Firestore
        AdzunaUtil --> AdzunaAPI
        EnvUtil --> SecretMgr
        TracedTools --> Langfuse
        TracingCfg --> Langfuse
    end

    classDef agent fill:#ADD8E6,stroke:#000;
    classDef tool fill:#90EE90,stroke:#000;
    classDef util fill:#90EE90,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
    classDef db fill:#FFFF00,stroke:#000;
    classDef cloud fill:#E0E0E0,stroke:#000;
    classDef api fill:#E0FFFF,stroke:#000;
```
