How I Keep Every Project Organized (Notes, Repos and All)

As the years go by my projects list kept growing. Sometimes I would have a separate name for the same thing in my notes (obsidian) and on disk (folder name), and even a different name for the remote repository (GitHub). It took me a while to go through everything and reorganize all my folders into categories, rename them to match the notes and have a 1-to-1 mapping between them. Ambiguity is the enemy of findability after all.

If something starts being repetitive needlessly, it’s a sign that I need to improve the system, and this post is about how I came to this point.

As of now, I have around 70 repositories on my laptop and a vault of a bit over two thousand notes Most of that arrived in about eighteen months: platforms for a tech hub programme, government portals, university work, prototypes for teammates, plus my own things.

Even before the reorganization I rarely got lost due to the powerful Everything (which I highly recommend). What motivates to keep things concise is the Single Source of Truth principle, though in this case I’m not sure if I’m using it correctly. The idea is that the note, the local folder and the remote repository should all have the same name and they should follow a predicable pattern:

There should be a single note per project, and it should be the index of that project.
The note should be the source of truth for the project, and it should contain all the metadata about it, including the name of the local folder and the remote repository.
The local folder should be named after the project, and it should contain the code and any other files related to the project.

This post is the current answer to that. Not the perfect system, just the one that survived contact with real work.

PARA, and the exact place it broke#

I started from PARA, which splits everything into four buckets:

1. Projects/ for things with a start and an end
2. Areas/ for things that just continue
3. Resources/ for reference material
4. Archives/ for the dead

Before PARA, I had a single Projects/ folder with a flat list of project notes. And from PARA I took a fancy for the first two: Projects and Areas. I don’t really use Resources or Archives (it’s an evolving system yknow, I might come back later to this).

NOTE
This is the part of the system I most expect to change again, and my rule is that I do not reorganize it without a specific reason written down. “It feels untidy” is not a reason.

Avoiding long lists#

First, this is on my Obsidian vault:

1. Projects/
├── Employer Folder/    work projects for my employer
├── Clientes/           external client work
├── Governo/            government platforms (from programmes, not contracts)
├── Ideias/             things that are still just ideas
├── Pessoais/           my own things (family projects, blog, etc)
└── UEM/                university-related, including my thesis system

But I simultaneously was working in the structure on disk, which was a flat C:\Users\Rei\Projects with all the repos in it. My aim was to keep things as close to the vault as possible (and vice versa), this is how it looked like:

C:\Users\Rei\Projects\
├── employerX-folder\
├── governo\
├── clientes\
├── uem\
├── pessoais\
├── _tools\
└── _archived\

I had to add a _tools folder for things that were not projects, and an _archived folder for things that were done and I did not want to see in the main list (there are always these projects from when you started and you cringe when you see them… yup, keeping it hidden it is).

Using the Dataview plugin, I can generate a list of all projects in the vault, grouped by area, and sorted by priority and other data I want to filter by.

One note per project, frontmatter as the only metadata#

Each project gets exactly one index note, from a template. All metadata lives in frontmatter.

---
tags:
  - Project
aliases:
  - SGIN
  - Sistema de Gestão de Incubadoras de Negócios
status: active          # idea | active | paused | done | archived
area: UEM
role: Dev (monografia)
priority: 🟥            # 🟥 / 🟨 / 🟩
start: 2023-11          # YYYY-MM
end: 2026-07
repo-local: uem\sgin-frontend, uem\sgin-backend
repo-github: https://github.com/reizen-desu/sgin-frontend
url:
---

To keep things manageable and predictable, I created a few rules for naming folders and repos:

Versions get -v1, -v2, -v3, and they must match the subdomain.
Apps that simulate a phone in the browser keep -mobile.
A native React Native port gets -rn (not so sure about this one yet, subject to change).

There’s no need to duplicate notes for versions#

Only for projects that take a very different approach, in this case they get a separate note. But for minimal changes, like a new version of the same platform, I keep it in the same note. The note is the source of truth, and it is easier to keep track of which version is live if there is only one note.

This works by creating a section named for example ## Versões in the existing note, and repo-local lists both folders. One note, several versions, one place where I remember which one is actually the live one.

Changelogs are generated from commits#

Every project note that has code can get a companion file, <Project> - Changelog.md. I do not write it by hand. It is generated from the repository’s commit history: resolve the repo from repo-local, read the commits for the period, group by month, most recent at the top, and translate them into something human-readable.

The moment it paid for itself#

Keeping things organized and easily discoverable (especially in Obsidian) means you can answer questions about your projects without having to waste time. Plus, you are open to using AI tools (Claude Code, Codex, etc.) to help you with that, since the data is structured and predictable.