resbuilder

The implementation centers on a single product promise: transform one source CV into one tailored resume for one target role while preserving factual truth, ATS compatibility, and production reliability.
To make that promise executable, the system defines strict invariants before generation starts:

• source CV is the only factual authority,
• target job description provides language targets, not new facts,
• output must remain editable and machine readable,
• final PDF must be exactly one A4 page,
• unsupported terms must be excluded rather than guessed.

This framing turns the task from open ended text generation into bounded document transformation.

End to end architecture

The runtime is organized as a staged workflow with explicit status transitions:

1. Upload intake and validation.
2. Job creation with template selection and rate limiting.
3. Queued execution with multi stage orchestration.
4. Multi agent generation and validation loops.
5. Rendering and artifact packaging.
6. Delivery and operator mirroring.
7. Job finalization, restart windows, and cleanup.

Each stage updates persisted state so users and operators can observe forward progress and failure location in real time.

Input handling and intake hardening

The upload flow enforces a constrained intake contract:

• email must be valid and normalized,
• job description must pass minimum context length,
• selected template must be in the supported public set,
• CV must be a text extractable PDF within size limits.

Uploads are staged through signed or scoped upload identifiers, then consumed exactly once during job creation to prevent accidental replay and orphaned references.

Rate limiting is applied at submission time by request IP and UTC day window.
The implementation includes development bypass behavior to preserve local iteration speed without weakening hosted protection.

Runtime modes and state management

The system supports two execution modes with a shared job contract:

• local mode for deterministic development and fast feedback,
• hosted mode for deployment with durable distributed state.

Local mode characteristics

• lightweight persistent store,
• filesystem backed artifacts,
• in process worker execution,
• straightforward debugging with local artifacts.

Hosted mode characteristics

• durable cloud database records,
• binary artifact storage in object like collections,
• workflow dispatched execution,
• resilient operation under concurrent traffic.

The mode boundary is explicit and typed so behavior remains predictable during deployment transitions.

Queueing and workflow orchestration

Queueing is a reliability control, not just a scaling tool.
The implementation avoids direct in request generation and uses asynchronous job processing with serializable status updates.

Core queue semantics:

• jobs start in queued,
• worker claims transitions to active stages,
• each stage is wrapped in timing, logging, and error attribution,
• terminal states are completed or failed.

Hosted execution is dispatched through internal workflow invocations with authenticated callback entry points.
Multiple base URL candidates are supported for deployment and local production style testing to avoid callback drift.

Multi agent design and responsibility boundaries

The generation pipeline is intentionally split into three responsibilities:

Agent 1: meta prompting

This stage synthesizes role specific reviewer instructions from the target job description and external role context.
It does not write resume content. It prepares the review policy.

Agent 2: evidence first reviewer

This stage compares source CV evidence against role requirements and emits structured analysis:

• ATS term inventory,
• section rewrite suggestions,
• supportable keyword plan,
• explicitly unsupported terms,
• evidence ledger for traceability,
• compactness guidance for one page target.

Agent 3: constrained builder

This stage generates the final markdown resume in strict JSON output shape.
It applies reviewer evidence and compactness constraints while preserving chronology and education semantics from the source.

This separation produces auditable behavior and sharply improves failure diagnosis.

Prompt engineering and output control

The implementation uses a layered prompting strategy:

• role specific meta prompting upstream,
• reviewer task prompts focused on extraction and classification,
• builder prompts focused on constrained rewriting.

Reliability techniques embedded in prompts:

• strict structured output requirements,
• fixed top level keys,
• contrastive examples for allowed and forbidden keyword insertion,
• explicit anti invention rules,
• compactness budgets and ordering priorities.

When a model violates schema or content rules, repair prompting is targeted and issue specific.
The repair message lists exact faults and required corrections rather than generic retry instructions.

Structured output validation pipeline

Model responses are treated as untrusted payloads and pass through:

1. JSON extraction normalization.
2. Schema validation for shape and required fields.
3. Semantic validation against domain rules.
4. Retry and repair if validation fails.

Validation includes:

• required section presence,
• heading consistency with source CV semantics,
• forbidden unsupported term detection,
• keyword support coverage checks,
• compactness policy checks.

This pipeline blocks unsafe outputs before they can reach rendering.

Grounding and anti-hallucination controls

Grounding enforcement is multi layer:

• reviewer classifies supportability per job term,
• builder is instructed to omit unsupported items,
• validator compares critical headings and chronology against source patterns,
• repair loops reference exact grounding faults.

The design preference is omission over invention.
If support is unclear, the system drops the claim.

One page A4 enforcement loop

One page output is enforced on rendered PDF, not inferred from markdown length.

Rendering loop:

1. normalize markdown and stage template assets,
2. generate HTML,
3. render PDF with headless browser runtime,
4. extract page count from produced PDF,
5. if count is not one, generate compactness repair instruction and rerun builder,
6. stop on success or repair budget exhaustion.

This creates deterministic output geometry across templates and prevents silent two page regressions.

Template framework and attribution model

Templates are managed as metadata driven registry entries with:

• public identifier,
• source attribution,
• preview metadata,
• rendering profile,
• builder notes for style and density behavior.

Artifact generation and packaging

For successful runs, the system produces:

• final PDF,
• editable markdown source,
• bundled source package,
• delivery archive package.

Artifacts are persisted according to runtime mode and associated with expiration windows.
Download endpoints enforce status checks, expiry checks, and asset existence checks.

Delivery strategy and operational mirrors

Delivery has two channels:

• user channel for success and failure notifications,
• operator mirror channel for observability and debugging.

Success notifications include download links and packaged artifacts.
Failure notifications include actionable messaging.
Operator mirrors can include artifact attachments for deeper incident triage.

This shortens diagnosis cycles and reduces blind failures.

Failure debug artifact strategy

When builder or render fails after repair budget:

• latest markdown attempt is persisted,
• latest model response payload is persisted,
• structured failure metadata is persisted,
• last repair message is persisted when available.

Debug persistence provides concrete evidence for prompt or validation tuning and reduces recurrence of ambiguous failure classes.

Stuck job and stale worker recovery

A production hardening addition addresses orphaned active states caused by deployment interruption:

• active jobs track updatedAt,
• stale active jobs beyond timeout are auto transitioned to failed,
• restart windows are issued for user recovery.

This prevents long lived building style stalls and restores deterministic user experience after infrastructure interruptions.

17. Security and privacy posture

Key controls include:

• input validation and schema enforcement,
• upload TTL and artifact TTL policies,
• scoped internal workflow tokens,
• restricted restart windows,
• masked email logging and minimized payload logs.

Operational override channels exist for controlled debugging but are explicit and environment gated.

SEO and discovery implementation

The public surface includes:

• canonical metadata,
• per route metadata,
• sitemap generation,
• robots policy,
• structured data,
• social preview image generation,
• analytics instrumentation.

SEO hardening is separated from generation quality so search growth does not compromise pipeline integrity.

CI and CD quality gates

Release confidence is achieved through layered gates:

• static analysis and linting,
• unit tests for contracts and validators,
• integration tests for pipeline behavior,
• frontend tests for user flow states,
• end to end tests for submission to delivery journey,
• predeploy benchmark checks on canonical fictional datasets.

Predeploy benchmark assertions include:

• successful completion across public templates,
• selected template preservation,
• one page output,
• zero unsupported additions,
• improved supported keyword carryover.

Only passing builds are deployment candidates.

Outcome

The final system behaves like a production document transformation platform with AI components, not a generic AI text generator.
By combining staged agent responsibilities, tool verified constraints, deterministic validation, recovery aware operations, and benchmark gated releases, the implementation delivers consistent, explainable, and restartable behavior at runtime.