Workspace Restructuring for Scalable Job Applications (Domain-Driven Structure)

[mohamedelawakey]

Workspace Restructuring Proposal

1. The Problem

The current repository structure suffers from two major design flaws when scaling the number of job applications:

1. LaTeX Auxiliary File Clutter: Compiling a LaTeX document generates multiple auxiliary files (.aux, .log, .out) alongside the .tex and .pdf files. This clutters the workspace and makes it extremely difficult to navigate and find the actual output files.
2. Poor Organization (Flat Structure): The repository currently separates all CVs into a cv/ directory and all cover letters into a cover_letters/ directory. If a user applies to 50 jobs, these folders become unmanageable dumping grounds. Searching for the exact CV and Cover Letter submitted to a specific company requires matching filenames manually.

Here is what the workspace looks like after generating documents for just 5 job applications:

CV Directory Clutter:

Cover Letters Directory Clutter:

2. The Proposed Solution

We propose shifting from a "File-Type Driven" structure to a "Domain-Driven" structure. Applications should be grouped by the entity they belong to: The Company and the Role.

2.1 Directory Restructuring

Instead of a flat global list, we will maintain the separation of cv/ and cover_letters/ (to support users who only want to generate one or the other independently), but apply the Company/Role hierarchy inside both.

Proposed Architecture:

ai-job-search/
├── cv/
│   ├── companies/
│   │   ├── Company_A/
│   │   │   ├── Role_X/
│   │   │   │   └── cv.pdf
│   │   │   └── Role_Y/
│   │   │       └── cv.pdf
│   │   ├── Company_B/
│   │   │   ├── Role_Z/
│   │   │   │   └── cv.pdf
│   │   │   └── Role_Z_2/ (If applied again for the same role)
├── cover_letters/
│   ├── companies/
│   │   ├── Company_A/
│   │   │   ├── Role_X/
│   │   │   │   └── cover_letter.pdf
│   │   │   └── Role_Y/
│   │   │       └── cover_letter.pdf
│   │   ├── Company_B/
│   │   │   ├── Role_Z/
│   │   │   │   └── cover_letter.pdf
│   │   │   └── Role_Z_2/
...

Benefits:

• Supports independent generation (a user can generate just a cover letter without cluttering a unified application folder).
• Keeps the Company/Role organization intact.
• Avoids overwriting files by auto-incrementing role folders (e.g., _2).

2.2 LaTeX Clutter Management

To solve the clutter issue, the system will isolate auxiliary files completely:

• All auxiliary files (.aux, .log, .out, etc.) will be directed into a hidden folder named .out/ inside the respective role directory.
• We will add .out/ to .gitignore so users never have to think about or commit these files.
• Note: Since standard LaTeX commands (pdflatex -output-directory=.out) will also put the .pdf inside .out/, the compilation script/command will automatically move the final .pdf back to the role folder so it remains visible to the user.

3. Implementation Plan

To submit this as a Contribution (PR) to the repository, the following files need to be updated:

1. CLAUDE.md / AGENTS.md:

   • Update the instructions to teach the AI assistant the new companies/[Company]/[Role]/ structure.
   • Remove references to dropping files in cv/ and cover_letters/.

2. .claude/skills/job-application-assistant/06-cover-letter-templates.md:

   • Update the expected output paths and the standard compile commands.
   • Embed the cleanup logic into the compile instructions (e.g., xelatex cover.tex && rm *.aux *.log *.out).

3. .gitignore:

   • Add .out/ and global ignores for LaTeX auxiliary files to ensure zero clutter is tracked by Git.

4. Template Migration:

   • Move the base templates (main_example.tex, cover.cls, OpenFonts/) into a dedicated templates/ folder so they are isolated from user-generated content.

5. Python Scripts (tools/):

   • tools/verify_layout.py & tools/verify_pdf.py: Update the hardcoded paths that expect files to be in the root of cv/ or cover_letters/.
   • tools/security_guards.py: Update the glob patterns (e.g., "cv/main_*.*") to match the new nested structure ("cv/companies/**/*.tex").

6. Tests (tests/):

   • Update integration tests (like test_apply_records_application.py, test_tracker_notes_csv_safe.py, and test_apply_page_count.py) that mock or assert the creation of files in the old flat structure.

7. Documentation:

   • Update README.md, SETUP.md, and documents/README.md to reflect the new directory trees.

[MadsLorentzen]

Thanks for writing this up with screenshots. Two different problems in it, with different answers.

The aux clutter is a real annoyance, and the fix is already in the workflow: /apply Step 5e ("Clean up build artifacts", since v1.1.0, July) tells the agent to delete .aux/.log/.out after the final clean compile, and .gitignore already ignores those extensions so they never reach git. If your runs leave them behind, that is the step not firing, and I would like to see it: open an issue with the tail of the /apply transcript around Step 5e and your framework_version from apply.md. If the step needs to be more mechanical (an explicit delete command per toolchain rather than prose), that is a small PR I would take.

The per-company folder tree I am going to decline, and I want to be clear it is not about the idea. The flat cv/main_<company>_<role>.tex naming is load-bearing: the cv/main_*.* and cover_letters/cover_*.* rules in .gitignore are what keep tailored CVs with real data out of public forks, security_guards.py, verify_pdf/verify_layout, the tracker and the tests all key on that layout, and every one of the 15k forks would meet the rename on its next rebase. A tree change is the kind of edit that is cheap to propose and expensive for everyone else, and the search problem it solves is already covered by the filename carrying company and role (plus the tracker row that records the path). If a fork wants the nested layout, it is a local change the agent can follow from your CLAUDE.md; it just will not be upstream's.

[mohamedelawakey]

Thanks a lot @MadsLorentzen for the detailed and insightful explanation!

Regarding the directory structure proposal, that makes total sense. I hadn't fully accounted for the security implications with .gitignore and the massive rebase friction it would cause for the 15k+ existing forks. I really appreciate you taking the time to explain the rationale behind keeping the flat layout load-bearing.

Regarding the build artifacts cleanup, I have just opened PR #531 to make Step 5e explicit with mechanical shell commands (rm -f *.aux *.log *.out... and rm -rf build/) per toolchain so that agents reliably execute the deletion step immediately after compilation.

Thanks again for creating and maintaining such a great tool!