# miguelmf-coder/matchkey-genai-maverick architecture

> Architecture diagram of the GitHub repository miguelmf-coder/matchkey-genai-maverick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/miguelmf-coder/matchkey-genai-maverick
- Repository: https://github.com/miguelmf-coder/matchkey-genai-maverick

## Overview

##### Project type and purpose
- MatchKey is a full-stack AI-driven job-matching platform.
- The README and file tree show a Streamlit frontend, a FastAPI backend, a PostgreSQL database, and multiple AI “agents” (OCR, skills extractor, HR Copilot, matching/co-teaching engines, scrapers).

##### File structure
- Top level:
- docker-compose.yml orchestrates three services: frontend, backend, db
- backend/ holds Dockerfile, requirements.txt, and the FastAPI app
- frontend/ holds Dockerfile, requirements.txt, app.py (Streamlit), utils, and role-based pages
- docs/ holds planning files
- backend/app:
- routers/: FastAPI endpoints (auth, candidates, companies, jobs, matching, copilot)
- services/: AI agents and utilities (OCR, scraping, matching, hr_copilot, notifications, recommendations)
- models/, db/: SQLAlchemy models, session, init/seed scripts
- schemas.py for Pydantic schemas
- frontend:
- app.py + utils.py as entry point
- candidate/ & company/ modules with Streamlit pages and call_ai integrations
- Config files:
- backend/Dockerfile, frontend/Dockerfile, docker-compose.yml

##### README for additional insights
- Architecture summary:
- Frontend: Streamlit (port 8501)
- Backend: FastAPI (port 8000)
- DB: PostgreSQL
- MCP Multi-Agent system comprising Document Parser, Skills Extractor, HR Copilot, Matching Engine, Co-Teaching, Scrapers
- Lists main REST routes and DB tables

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Streamlit Frontend" 
        direction TB
        UI["Streamlit UI (8501)"]:::frontend
        UI -->|HTTP| API
    end

    %% Backend Layer
    subgraph "FastAPI Backend" 
        direction TB
        API["FastAPI API (8000)"]:::backend

        subgraph "Routers"
            direction TB
            Auth["auth.py"]:::router
            Candidates["candidates.py"]:::router
            Companies["companies.py"]:::router
            Jobs["jobs.py"]:::router
            Copilot["copilot.py"]:::router
            MatchingRouter["matching.py"]:::router
        end

        subgraph "Services (MCP Multi-Agent)"
            direction TB
            subgraph "OCR / Document Parser"
                DP["Document Parser"]:::agent
            end
            subgraph "Skills Extractor"
                SE["Skills Extractor"]:::agent
            end
            subgraph "HR Copilot"
                HC["HR Copilot"]:::agent
            end
            subgraph "Matching Engine"
                ME["Matching Engine"]:::agent
            end
            subgraph "Co-Teaching Engine"
                CTE["Co-Teaching Engine"]:::agent
            end
            subgraph "Scraping Services"
                direction TB
                SC1["Companies Scraper"]:::agent
                SC2["Jobs Scraper"]:::agent
                SC3["Universities Scraper"]:::agent
                SC4["Courses Scraper"]:::agent
            end
            Notifications["Notifications"]:::agent
            Recommendations["Recommendations"]:::agent
        end

        subgraph "DB Layer"
            direction TB
            ORM["SQLAlchemy Session"]:::backend
            API --> ORM
            ORM --> DB
        end

        API -->|routes| Auth
        API -->|routes| Candidates
        API -->|routes| Companies
        API -->|routes| Jobs
        API -->|routes| Copilot
        API -->|routes| MatchingRouter

        API -->|calls| DP
        DP -->|parsed docs| SE
        SE -->|skills JSON| HC
        HC -->|copilot data| ME
        ME -->|matches| API

        API -->|calls| CTE
        API -->|calls| Notifications
        API -->|calls| Recommendations

        SC1 -->|seed/update| ORM
        SC2 -->|seed/update| ORM
        SC3 -->|seed/update| ORM
        SC4 -->|seed/update| ORM
    end

    DB["PostgreSQL"]:::db

    %% Click Events
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/app.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/utils.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/candidate/dashboard.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/candidate/jobs.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/candidate/profile.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/candidate/improve.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/candidate/call_ai.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/company/dashboard.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/company/create_job.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/company/profile.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/company/analytics.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/company/co_teaching.py"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/tree/main/frontend/Dockerfile"
    click UI "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/requirements.txt"

    click API "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/main.py"
    click Auth "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/routers/auth.py"
    click Candidates "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/routers/candidates.py"
    click Companies "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/routers/companies.py"
    click Jobs "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/routers/jobs.py"
    click Copilot "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/routers/copilot.py"
    click MatchingRouter "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/routers/matching.py"
    click ORM "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/database.py"
    click DB "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/db/session.py"
    click DB "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/db/init_db.py"
    click DB "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/docker-compose.yml"

    click DP "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/ocr/document_parser.py"
    click SE "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/skills/skills_extractor.py"
    click HC "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/hr_copilot/hr_copilot_tool.py"
    click ME "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/matching/matching_engine.py"
    click CTE "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/frontend/company/co_teaching.py"

    click SC1 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/companies/companies_scrapper.py"
    click SC1 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/companies/companies_base_info.py"
    click SC1 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/companies/companies_raw_text.py"
    click SC1 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/companies/companies_values_scraper.py"

    click SC2 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/jobs/jobs_scraper.py"
    click SC2 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/jobs/descriptions_scraper.py"
    click SC2 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/jobs/llm_scraper.py"

    click SC3 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/universities/universities_base_info.py"
    click SC3 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/universities/universities_raw_text.py"
    click SC3 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/universities/universities_relevant_links.py"
    click SC3 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/universities/universities_values_scraper.py"

    click SC4 "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/scraping/courses/courses_scraper.py"

    click Notifications "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/notifications/email_service.py"
    click Recommendations "https://github.com/miguelmf-coder/matchkey-genai-maverick/blob/main/backend/app/services/recommendations/courses_recommender.py"

    %% Styles
    classDef frontend fill:#E8F1FF,stroke:#3E77B6,color:#000;
    classDef backend fill:#FFF4E6,stroke:#FFA500,color:#000;
    classDef db fill:#E6FFEA,stroke:#2E8B57,color:#000;
    classDef agent fill:#F0E6FF,stroke:#8A2BE2,color:#000;
    classDef router fill:#FFE6E6,stroke:#FF4500,color:#000;
```
