# soaraway/taleq architecture

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

- Interactive diagram: https://gitdiagram.com/soaraway/taleq
- Repository: https://github.com/soaraway/taleq

## Overview

##### Project Type and Purpose
- This is a Next.js–based full-stack talent acquisition web application ("taleQ") that leverages AI to screen resumes, match candidates to jobs, and schedule interviews.
- Key features (from README): resume screening, AI–based matching/scoring, spam/fake resume detection, customizable job requirements, PDF generation, notification, file uploads, calendar view.

##### File Structure Analysis
- Top-level files: configuration for Next.js, ESLint, PostCSS, package.json, plus components.json (deployment metadata).
- `public/`: static assets.
- `src/app/`: Next.js App Router structure, with API routes under `src/app/api/{generate-pdf, notify-interview, upload-jobs, upload-resume}/route.js`.
- `src/components/`: reusable React UI components (Calendar, JobPosting, SearchBar, Settings, UploadResume, etc.) and a `ui/` subfolder for primitive UI controls (button, card, table, etc.).
- `src/lib/utils.js`: shared utility functions (e.g., file validation, AI integration helpers).

##### Architecture Overview
- Browser (user) interacts with the Next.js Frontend (SSR/SSG + client-side React).
- Frontend calls serverless API Routes (hosted on Vercel or Node.js env) for:
a. Resume upload
b. Job posting upload
c. PDF generation
d. Interview notifications
- API routes orchestrate:
- File storage (e.g., S3 or Vercel Blob)
- Database operations (e.g., MongoDB, PostgreSQL) for jobs, resumes, users
- External AI service calls (e.g., OpenAI) for resume screening & matching
- Email/SMS service (e.g., SendGrid, Twilio) for notifications
- Future modules (per README “Things to do”): user authentication, calendar DB, email ingestion.

##### Components
- Frontend Layer
- User’s Browser / Mobile Client
- Next.js App (React)
- Backend Layer (Serverless Functions)
- UploadResume Service
- UploadJobs Service
- GeneratePDF Service
- NotifyInterview Service
- Data Storage
- Blob/File Storage (resumes, PDF)
- Database (job postings, resume metadata, user data, schedules)
- External Services
- AI/ML Engine (resume screening, spam detection, candidate scoring)
- Email/SMS Gateway
- Auth Provider (future)
- Utilities & Shared Libraries
- `src/lib/utils.js` for shared logic

##### Relationships and Data Flows
- Frontend → API Routes (POST `/api/upload-resume`, etc.)
- API Routes → File Storage (uploading CVs)
- API Routes → Database (CRUD operations)
- API Routes → AI Service (screening, matching) → back to DB or Frontend
- API Routes → Email/SMS Service for notifications
- API Routes → PDF Generation component → Blob Storage → returns PDF URL

##### Architectural Patterns & Principles
- Separation of Concerns:
- UI vs. API vs. Data Stores
- Micro-services style (each API route is its own function)
- Serverless design (deployable on Vercel Functions or AWS Lambda)
- Use of React component hierarchy for UI primitives vs. domain components
- Future extensibility points: authentication, calendar subsystem

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["User Browser/Mobile"]:::frontend
        NextJS["Next.js Frontend"]:::frontend
        MainPage["Main Page (page.jsx)"]:::frontend
        Layout["Global Layout (layout.js)"]:::frontend
        Globals["Global Styles (globals.css)"]:::frontend
        subgraph "Core UI Components"
            direction TB
            Calendar["Calendar"]:::frontend
            JobPosting["JobPosting"]:::frontend
            SearchBar["SearchBar"]:::frontend
            Settings["Settings"]:::frontend
            UploadResumeComp["UploadResume"]:::frontend
        end
        subgraph "Primitive UI Controls"
            direction TB
            Button["Button"]:::frontend
            Card["Card"]:::frontend
            Checkbox["Checkbox"]:::frontend
            Switch["Switch"]:::frontend
            Table["Table"]:::frontend
            UploadFile["UploadFile"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Serverless Functions"
        direction TB
        UploadResume["UploadResume API"]:::backend
        UploadJobs["UploadJobs API"]:::backend
        GeneratePDF["GeneratePDF API"]:::backend
        NotifyInterview["NotifyInterview API"]:::backend
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        Blob["Blob Storage\n(Resumes, PDFs)"]:::datastore
        DB["Database\n(Jobs, Users, Schedules)"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AI["AI Service\n(Screening/Matching)"]:::external
        Email["Email/SMS Service"]:::external
        AuthProvider["Auth Provider\n(future)"]:::external
    end

    %% Utilities
    Utils["Shared Utilities (utils.js)"]:::util

    %% Connections
    Browser -->|"page request / form submit"| NextJS
    NextJS -->|"POST /api/upload-resume"| UploadResume
    NextJS -->|"POST /api/upload-jobs"| UploadJobs
    NextJS -->|"POST /api/generate-pdf"| GeneratePDF
    NextJS -->|"POST /api/notify-interview"| NotifyInterview

    UploadResume -->|"store file"| Blob
    UploadResume -->|"save metadata"| DB
    UploadResume -->|"screen/rescore"| AI
    AI -->|"update scores"| DB

    UploadJobs -->|"save job"| DB

    GeneratePDF -->|"generate PDF"| Blob
    Blob -->|"return URL"| NextJS

    NotifyInterview -->|"send notification"| Email

    UploadResume --> Utils
    UploadJobs --> Utils
    GeneratePDF --> Utils
    NotifyInterview --> Utils

    %% Click Events
    click NextJS "https://github.com/soaraway/taleq/tree/master/src/app"
    click MainPage "https://github.com/soaraway/taleq/blob/master/src/app/page.jsx"
    click Layout "https://github.com/soaraway/taleq/blob/master/src/app/layout.js"
    click Globals "https://github.com/soaraway/taleq/blob/master/src/app/globals.css"
    click UploadResume "https://github.com/soaraway/taleq/blob/master/src/app/api/upload-resume/route.js"
    click UploadJobs "https://github.com/soaraway/taleq/blob/master/src/app/api/upload-jobs/route.js"
    click GeneratePDF "https://github.com/soaraway/taleq/blob/master/src/app/api/generate-pdf/route.js"
    click NotifyInterview "https://github.com/soaraway/taleq/blob/master/src/app/api/notify-interview/route.js"
    click Utils "https://github.com/soaraway/taleq/blob/master/src/lib/utils.js"
    click Calendar "https://github.com/soaraway/taleq/blob/master/src/components/Calendar.jsx"
    click JobPosting "https://github.com/soaraway/taleq/blob/master/src/components/JobPosting.jsx"
    click SearchBar "https://github.com/soaraway/taleq/blob/master/src/components/SearchBar.jsx"
    click Settings "https://github.com/soaraway/taleq/blob/master/src/components/Settings.jsx"
    click UploadResumeComp "https://github.com/soaraway/taleq/blob/master/src/components/UploadResume.jsx"
    click Button "https://github.com/soaraway/taleq/blob/master/src/components/ui/button.jsx"
    click Card "https://github.com/soaraway/taleq/blob/master/src/components/ui/card.jsx"
    click Checkbox "https://github.com/soaraway/taleq/blob/master/src/components/ui/checkbox.jsx"
    click Switch "https://github.com/soaraway/taleq/blob/master/src/components/ui/switch.jsx"
    click Table "https://github.com/soaraway/taleq/blob/master/src/components/ui/table.jsx"
    click UploadFile "https://github.com/soaraway/taleq/blob/master/src/components/ui/UploadFile.jsx"

    %% Styles
    classDef frontend fill:#E0F2FE,stroke:#0369A1,color:#0369A1
    classDef backend fill:#ECFDF5,stroke:#059669,color:#059669
    classDef datastore fill:#FFF7ED,stroke:#EA580C,color:#EA580C
    classDef external fill:#F5F3FF,stroke:#7C3AED,color:#7C3AED
    classDef util fill:#F3F4F6,stroke:#4B5563,color:#4B5563
```
