Resume Generation

The resume generation subsystem orchestrates the process of retrieving, validating, optionally transforming, formatting, and caching user resumes. It supports multiple output formats, theme selection including random theme redirection, and integration with a large language model (LLM) for resume transformation based on user prompts.

Purpose and Scope

This page documents the internal mechanisms of the resume generation pipeline, including validation of input parameters and resume data, fetching resumes from GitHub Gists, optional transformation using an LLM, formatting according to selected themes and output formats, and caching of resume data. It does not cover the implementation details of individual formatters or theme rendering engines beyond error handling. For error handling templates and theme error rendering, see the errorTemplate and themeErrorTemplate pages.

Architecture Overview

The resume generation pipeline is composed of several cooperating components: input validation, resume retrieval from GitHub Gists, resume validation against a JSON schema, optional transformation via an LLM, formatting with a selected formatter and theme, and asynchronous caching of the resume data. The main entry point is the generateResume function, which coordinates these stages.

Diagram: Data flow through the resume generation pipeline

Sources: apps/registry/lib/generateResume.js:10-125, apps/registry/lib/generateResume/validation.js:20-50, apps/registry/lib/getResumeGist.js:9-63, apps/registry/lib/generateResume/transformResumeWithLLM.js:63-123, apps/registry/lib/generateResume/formatResume.js:4-37, apps/registry/lib/generateResume/cacheResume.js:3-31

generateResume

Purpose: The central orchestrator that generates a resume output for a given username, output format, and optional query parameters including theme, gist name, and LLM prompt.

Primary file: apps/registry/lib/generateResume.js:10-125

Key behaviors:

Extracts theme, gistname, and llm parameters from the query object.
Validates the requested output extension using validateExtension(). Returns an error if invalid.
Selects the appropriate formatter for the requested extension; returns an error if none exists.
Retrieves the resume JSON from the user's GitHub Gist via getResumeGist(). Returns an error if retrieval fails.
Validates the retrieved resume JSON against the schema using validateResume(). Returns validation errors if any.
If an LLM prompt is provided, transforms the resume using transformResumeWithLLM().
Determines the theme to use based on query, resume metadata, or defaults to 'elegant'.
If the theme is 'random', generates a redirect HTML page to a randomly selected theme.
Asynchronously caches the raw resume data using cacheResume() without blocking the response.
Formats the (possibly transformed) resume using the selected formatter and options.
Returns the formatted content and headers or error objects as appropriate.

How It Works:

The function begins by destructuring the theme, gistname, and llm parameters from the query.
It validates the requested output format extension and ensures a formatter exists.
It calls getResumeGist(username, gistname) to fetch the resume JSON from GitHub.
The resume is validated against the JSON schema using validateResume().
If an LLM prompt is provided, it calls transformResumeWithLLM(resume, llm) to apply user-specified transformations.
The theme is selected from the query, resume metadata, or defaults.
If the theme is 'random', it returns a redirect HTML page to a randomly chosen theme.
The resume is asynchronously cached to Supabase for future use.
Finally, the resume is formatted using the selected formatter and returned.

const generateResume = async (username, extension = 'template', query = {}) => {
  const { theme, gistname, llm } = query;
  const formatter = formatters[extension];

  const { error: extensionError } = validateExtension(extension);
  if (extensionError) return extensionError;

  if (!formatter) {
    return buildError(ERROR_CODES.UNKNOWN_FORMATTER);
  }

  const { error: gistError, resume } = await getResumeGist(username, gistname);
  if (gistError) {
    return buildError(gistError);
  }

  const { error: validationError } = validateResume(resume);
  if (validationError) return validationError;

  let transformedResume = resume;
  if (llm) {
    transformedResume = await transformResumeWithLLM(resume, llm);
  }

  let selectedTheme = theme || transformedResume.meta?.theme || 'elegant';
  selectedTheme = selectedTheme.toLowerCase();

  if (selectedTheme === 'random') {
    const randomTheme = getRandomTheme();
    const redirectUrl = `/${username}?theme=${randomTheme}${gistname ? `&gistname=${gistname}` : ''}`;
    const redirectHtml = `...`; // HTML redirect page

    return {
      content: redirectHtml,
      headers: [{ key: 'Content-Type', value: 'text/html; charset=utf-8' }],
    };
  }

  (async () => {
    await cacheResume(username, resume);
  })();

  const options = { ...query, theme: selectedTheme, username };
  return formatResume(transformedResume, formatter, options);
};

Sources: apps/registry/lib/generateResume.js:10-125

Extension Validation

Purpose: Ensures that the requested output format extension is supported by the system.

Primary file: apps/registry/lib/generateResume/validation.js:20-26

The system maintains a set of valid extensions (EXTENSIONS). The validateExtension function checks if the requested extension is in this set. If not, it returns an error object indicating an invalid extension.

const validateExtension = (extension) => {
  if (!EXTENSIONS.has(extension)) {
    return { error: buildError(ERROR_CODES.INVALID_EXTENSION) };
  }
  return { error: null };
};

Sources: apps/registry/lib/generateResume/validation.js:20-26

Resume Validation

Purpose: Validates the structure and content of the resume JSON against a predefined JSON schema to ensure correctness.

Primary file: apps/registry/lib/generateResume/validation.js:28-50

Key behaviors:

Allows bypassing validation if the resume metadata contains meta.skipValidation set to true.
Uses the jsonschema Validator to validate the resume against the schema.
Returns detailed validation errors wrapped in an error object if validation fails.
Returns no error if validation passes or is skipped.

const validateResume = (resume) => {
  if (resume?.meta?.skipValidation === true) {
    logger.info(
      { skipValidation: true },
      'Schema validation bypassed via meta.skipValidation flag'
    );
    return { error: null };
  }

  const v = new Validator();
  const validation = v.validate(resume, schema);

  if (!validation.valid) {
    return {
      error: buildError(ERROR_CODES.RESUME_SCHEMA_ERROR, {
        validation: validation.errors,
      }),
    };
  }

  return { error: null };
};

Sources: apps/registry/lib/generateResume/validation.js:28-50

Resume Caching

Purpose: Asynchronously caches the raw resume JSON data in a Supabase database keyed by username to support future features like resume history or analytics.

Primary file: apps/registry/lib/generateResume/cacheResume.js:3-31

Key behaviors:

Skips caching if the SUPABASE_KEY environment variable is not set, avoiding errors in CI or test environments.
Lazily imports the Supabase client to reduce startup overhead.
Uses Supabase's upsert method to insert or update the resume record keyed by username.
Logs errors if caching fails but does not propagate them, ensuring caching is non-blocking.

const cacheResume = async (username, resume) => {
  const supabaseKey = process.env.SUPABASE_KEY;
  if (!supabaseKey) {
    logger.debug('Skipping resume caching: SUPABASE_KEY not configured');
    return;
  }

  try {
    const { createClient } = require('@supabase/supabase-js');
    const supabaseUrl = 'https://itxuhvvwryeuzuyihpkp.supabase.co';
    const supabase = createClient(supabaseUrl, supabaseKey);

    await supabase
      .from('resumes')
      .upsert(
        {
          username,
          resume: JSON.stringify(resume),
          updated_at: new Date(),
        },
        { onConflict: 'username' }
      )
      .select();
  } catch (error) {
    logger.error({ error: error.message, username }, 'Failed to cache resume');
  }
};

Sources: apps/registry/lib/generateResume/cacheResume.js:3-31

Resume Formatting

Purpose: Converts the resume JSON into the requested output format using the selected formatter and theme, handling errors related to missing or faulty themes.

Primary file: apps/registry/lib/generateResume/formatResume.js:4-37

Key behaviors:

Calls the formatter's format method with the resume and options.
Catches and logs errors during formatting.
Returns a specific error if the theme is missing.
Returns a generic template error with full error details for other failures.
Returns the formatted content and optional headers on success.

const formatResume = async (resume, formatter, options) => {
  let formatted = {};
  const themeName = options?.theme || 'unknown';

  try {
    formatted = await formatter.format(resume, options);
  } catch (e) {
    logger.error(
      { themeName, error: e.message, stack: e.stack },
      'Theme rendering error'
    );

    if (e.message === 'theme-missing') {
      return {
        error: buildError(ERROR_CODES.TEMPLATE_MISSING, { themeName }),
      };
    }

    return {
      error: buildError(ERROR_CODES.UNKNOWN_TEMPLATE_ERROR, {
        themeName,
        error: {
          message: e.message,
          stack: e.stack,
          name: e.name,
        },
      }),
    };
  }

  return { content: formatted.content, headers: formatted.headers || [] };
};

Sources: apps/registry/lib/generateResume/formatResume.js:4-37

Resume Transformation with LLM

Purpose: Applies user-specified transformations to the resume JSON using a large language model (LLM), returning a modified resume with only the requested changes applied.

Primary file: apps/registry/lib/generateResume/transformResumeWithLLM.js:63-123

Key behaviors:

Skips transformation if the OPENAI_API_KEY environment variable is not set.
Skips transformation if the prompt is empty or invalid.
Sends only essential resume fields (basics, first 5 work entries, first 10 skills, education) to the LLM to reduce token usage.
Uses a system prompt instructing the LLM to return only a JSON object with changed fields.
Parses the LLM response to extract JSON changes enclosed in markdown code blocks.
Applies the changes to a deep copy of the original resume using a helper function.
Logs timing and errors during the transformation process.
Returns the original resume if any error occurs.

async function transformResumeWithLLM(resume, prompt) {
  if (!process.env.OPENAI_API_KEY) {
    logger.warn('OPENAI_API_KEY not set, skipping LLM transformation');
    return resume;
  }

  if (!prompt || typeof prompt !== 'string' || prompt.trim().length === 0) {
    return resume;
  }

  const startTime = Date.now();

  try {
    logger.info(
      { prompt: prompt.substring(0, 100) },
      'Starting LLM resume transformation'
    );

    const essentialResume = {
      basics: resume.basics,
      work: resume.work?.slice(0, 5),
      skills: resume.skills?.slice(0, 10),
      education: resume.education,
    };

    const result = await generateText({
      model: openai('gpt-4.1-mini'),
      system: SYSTEM_PROMPT,
      prompt: `Resume:\n${JSON.stringify(
        essentialResume,
        null,
        2
      )}\n\nRequest: ${prompt}\n\nReturn ONLY a JSON object with the changed fields.`,
    });

    const duration = Date.now() - startTime;
    logger.info(
      { duration, prompt: prompt.substring(0, 100) },
      'LLM transformation completed'
    );

    const text = result.text.trim();
    const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/) || [
      null,
      text,
    ];
    const jsonStr = jsonMatch[1].trim();
    const changes = JSON.parse(jsonStr);

    return applyChanges(resume, changes);
  } catch (error) {
    logger.error(
      { error: error.message, prompt: prompt.substring(0, 100) },
      'LLM transformation failed'
    );
    return resume;
  }
}

Sources: apps/registry/lib/generateResume/transformResumeWithLLM.js:63-123

GitHub Gist Resume Retrieval

Purpose: Fetches the resume JSON from a user's GitHub Gist, optionally using a specified gist filename, handling errors related to network, JSON parsing, and gist existence.

Primary file: apps/registry/lib/getResumeGist.js:9-63

Key behaviors:

Requests the list of gists for the user via GitHub API, optionally using a GitHub token for authentication.
Searches the gists for a file matching the requested gist name.
Returns an error if the gist or file does not exist.
Fetches the raw JSON content of the gist file.
Returns errors for JSON parsing failures or unknown gist errors.
Returns the parsed resume JSON on success.

const getResumeGist = async (username, gistname = RESUME_GIST_NAME) => {
  let gistData = null;
  try {
    gistData = await axios.get(
      `https://api.github.com/users/${username}/gists?per_page=100`,
      {
        headers: {
          ...(GITHUB_TOKEN ? { Authorization: 'Bearer ' + GITHUB_TOKEN } : {}),
        },
      }
    );
  } catch (e) {
    logger.error({ error: e.message, username }, 'Failed to fetch gists');
    return buildError(ERROR_CODES.INVALID_USERNAME);
  }

  if (!gistData.data) {
    return buildError(ERROR_CODES.GIST_UNKNOWN_ERROR);
  }

  const resumeUrl = find(gistData.data, (f) => {
    return f.files[gistname];
  });

  if (!resumeUrl) {
    return buildError(ERROR_CODES.NON_EXISTENT_GIST);
  }

  const gistId = resumeUrl.id;

  let resumeRes = {};

  try {
    const fullResumeGistUrl = `https://gist.githubusercontent.com/${username}/${gistId}/raw?cachebust=${new Date().getTime()}`;

    resumeRes = await axios({
      method: 'GET',
      headers: { 'content-type': 'application/json' },
      url: fullResumeGistUrl,
    });
  } catch (e) {
    if (e.message?.includes('JSON') || e.name === 'SyntaxError') {
      return buildError(ERROR_CODES.RESUME_NOT_VALID_JSON);
    }
    return buildError(ERROR_CODES.GIST_UNKNOWN_ERROR);
  }

  if (typeof resumeRes.data !== 'object' || resumeRes.data === null) {
    return buildError(ERROR_CODES.RESUME_NOT_VALID_JSON);
  }

  return { resume: resumeRes.data };
};

Sources: apps/registry/lib/getResumeGist.js:9-63

Key Relationships

The resume generation subsystem depends on:

The GitHub API for fetching user gists (getResumeGist).
The JSON schema and validator for resume validation (validateResume).
Formatters keyed by output extension for rendering resumes (formatResume).
The OpenAI API for optional LLM-based resume transformation (transformResumeWithLLM).
Supabase for asynchronous caching of resume data (cacheResume).
Error construction utilities for consistent error reporting (buildError).

It is a core component feeding formatted resume content to downstream consumers such as web servers or API endpoints.

Relationships to adjacent subsystems

Sources: apps/registry/lib/generateResume.js:10-125, apps/registry/lib/getResumeGist.js:9-63, apps/registry/lib/generateResume/validation.js:28-50

`setByPath`, `keys`, `current`, `i`, `nextKey`, `isNextArray` in apps/registry/lib/generateResume/transformResumeWithLLM.js

Introduction

These symbols collectively implement a utility to deeply set a value within a nested JavaScript object using a dot-notation path string. This mechanism is critical for applying partial updates to deeply nested resume objects based on changes computed by the LLM. It handles both object and array structures dynamically, ensuring the path exists before assignment.

`setByPath` (function)

Purpose: Mutates an object by setting a value at a nested location specified by a dot-separated path string, creating intermediate objects or arrays as needed.

Parameters:

obj (Object): The target object to modify.
path (string): Dot-notation string specifying the nested property path (e.g., "work.0.summary").
value (any): The value to assign at the specified path.

Behavior:

Splits the path into keys by . delimiter.
Iterates through all keys except the last, traversing or creating nested objects or arrays as necessary.
Determines whether to create an array or object for the next key by checking if the next key is a numeric index (isNextArray).
Assigns the value to the final key in the path.

Edge cases and tradeoffs:

Numeric keys are interpreted as array indices, enabling support for array item updates.
If intermediate keys do not exist, they are created as empty arrays or objects based on the next key type, which avoids runtime errors but may silently create unexpected structures if the path is malformed.
Does not validate existing types at intermediate keys; overwrites if incompatible.

function setByPath(obj, path, value) {
  const keys = path.split('.');
  let current = obj;

  for (let i = 0; i < keys.length - 1; i++) {
    const key = keys[i];
    const nextKey = keys[i + 1];
    const isNextArray = !isNaN(parseInt(nextKey, 10));

    if (!(key in current)) {
      current[key] = isNextArray ? [] : {};
    }
    current = current[key];
  }

  current[keys[keys.length - 1]] = value;
}

`keys` (variable)

Purpose: Holds the array of keys derived from splitting the dot-notation path string inside setByPath.

Type: string[]