DEV Community: LkSvn

A Rename Can Be a Migration in a Local-First Markdown System

LkSvn — Tue, 11 Aug 2026 22:13:01 +0000

It is easy to assume that an application backed by Markdown files avoids the
hard parts of data migration. There is no database schema to alter, no foreign
key constraint to update, and no migration framework to run.

That assumption stops working as soon as filenames, metadata, links, and assets
begin carrying identity.

I encountered this while improving a Vue-based manager for a local card
collection. Each saved card is a Markdown note that can link to other notes and
reference a local image. Older records predated the current identity rules, so
an audit found notes with missing IDs, duplicate IDs, and filenames that no
longer matched their saved card printing.

Why changing one property was not enough

The first repair step looked small: select the correct printing and save its
stable identifier. But that identifier affected several parts of the system:

the expected Markdown filename
the image filename and Cover property
links written in other Markdown notes
duplicate identity checks
filename collision checks
cleanup of the previous image

Updating only the front matter would leave the collection internally
inconsistent. Renaming only the note could break Obsidian links. Deleting the
old image could break another note if the asset was shared.

The operation was not a field edit. It was a migration.

Treating the filesystem as a data model

The repair flow became an explicit sequence:

Validate the requested identity.
Reject duplicate identities and target filename collisions.
Rename the note to its stable filename.
Rewrite Markdown and wiki links that reference the previous name.
Update the card image and Cover metadata.
Remove obsolete assets only after confirming they are unused.
Run the collection audit again.

The ordering matters. A failed rename should not leave references pointing to a
file that never moved. Cleanup should happen after the new state is valid, not
before it. Collision checks should fail safely instead of guessing which file
is authoritative.

This is similar to a database migration even though the storage mechanism is
different. The invariants still need to be explicit:

one stable identity belongs to one saved card
a stable filename must not overwrite another note
references must continue resolving after a rename
a shared asset must not be removed while another note still uses it

Verification beyond the happy path

The backend route tests cover validation, collision handling, link rewriting,
and repair behavior. A complete browser lifecycle test exercises the feature
through the real application flow.

After the repair work was completed, the collection was normalized and the
audit reported no remaining identity or filename issues.

The most important verification was not that a card could be repaired once. It
was that the operation failed safely when the target identity or filename was
already in use, and that rerunning the audit produced a stable result.

What I learned

Local-first storage changes the infrastructure, not the need for integrity.

In a relational database, relationships are visible in tables, keys, and
constraints. In a filesystem-backed application, they may be distributed
across filenames, front matter, links, configuration, and shared assets. That
makes them easier to overlook, not less important.

The practical rule I am keeping is:

If changing a value can invalidate references elsewhere, the operation should
be designed and verified as a migration.

Plain files are a powerful source of truth, but they still deserve explicit
identity rules, safe failure modes, and repeatable audits.

Building a Local-First Personal Finance System in Obsidian

LkSvn — Tue, 04 Aug 2026 12:45:13 +0000

For several years, I tracked personal finances in monthly spreadsheets. The
system worked, but the format evolved over time, recurring expenses were easy to
miss, and reviewing accounts payable and receivable required navigating many
disconnected files.

When I started consolidating the data, I did not want to create another hosted
application or move sensitive financial information into an external service.
I wanted the data to remain local, portable, and understandable without a
special runtime.

Obsidian provided a useful middle ground: Markdown files for durable storage,
links for relationships, Bases for structured views, and QuickAdd for lightweight
automation.

One transaction, one Markdown file

The central design decision is simple: every financial transaction is an
individual Markdown note with YAML properties.

person:
  - "[[FINANCES/PEOPLE/Example person|Example person]]"
movement: pay
period: 2030-01
period_note: "[[FINANCES/PERIODS/2030-01|2030-01]]"
description: Fictional bill
amount: 100.00
due_date: 2030-01-10
status: pending
category:
  - "[[FINANCES/CATEGORIES/Other|Other]]"

This is more verbose than a spreadsheet row, but it has useful properties:

the data remains ordinary text
every transaction can link to related notes
Git can show meaningful changes
searches and scripts do not depend on a proprietary database
Obsidian can present the same files through multiple views

The source of truth is the transaction note. Dashboards and tables only query
those notes, which avoids having to update the same financial entry in multiple
places.

Relationships through links

People, categories, periods, and recurrence definitions are also notes. A
transaction links to them through properties instead of repeating loosely
normalized text.

This improves filtering and navigation while also making Obsidian's graph and
backlinks useful. The graph is not the primary interface for financial analysis,
but it provides a quick view of how records connect to people, periods, and
categories.

Dashboards with Bases

Obsidian Bases turns the Markdown collection into database-like views without
changing the storage format.

The template includes views for:

the current month
pending transactions
accounts payable and receivable
completed and cancelled records
installments and recurring transactions
expenses grouped by category
monthly expenses

Movement and status formulas add visual markers so inflows, outflows, pending
items, and completed items are easier to distinguish at a glance.

Recurring transactions without duplicate sources of truth

Recurring expenses initially created an awkward problem. Editing both a
recurrence definition and an already generated monthly transaction meant the
same information existed in two places.

The revised model gives each file a clear responsibility:

a recurrence note describes the rule
a generated transaction represents one specific month
dashboards only read transaction notes

Fixed expenses use their configured expected amount. Variable expenses can use
the latest matching transaction as the starting value for a new month. Charges
already included in a credit card bill can be documented without generating an
additional transaction.

The monthly generator is idempotent: running it again for the same period does
not create duplicate transactions. Installment plans also stop after their final
configured period.

QuickAdd as the interaction layer

Two QuickAdd actions provide the main workflow:

create a new financial transaction
generate the transactions for a new month

The scripts create the required period note and transaction file, while the
user still edits ordinary Markdown afterward. QuickAdd is an interaction layer,
not a separate database.

Privacy and portability

The vault is synchronized between devices using an independent file-sync setup.
The finance model itself does not require a cloud account or a finance-specific
provider.

For the public template, generated people, periods, transactions, Obsidian
workspace state, and environment files are excluded through .gitignore. The
repository contains only the reusable structure, scripts, documentation, and
fictional screenshots.

Local-first does not eliminate the need for backups or device security, but it
does keep ownership and portability explicit.

What I learned

This project reinforced a few ideas that also apply outside personal finance:

A single source of truth matters even in small personal systems.
Automation should remove repetitive input without hiding the underlying data.
Plain files can support surprisingly rich workflows when metadata and links are modeled deliberately.
A useful internal tool does not need to become a hosted product.
Publishing a sanitized template requires treating privacy as part of the architecture, not as a final cleanup step.

The resulting project is available here:

https://github.com/lksvn/obsidian-finances-template

It includes the empty vault structure, setup documentation, Bases definitions,
QuickAdd scripts, recurrence rules, and fictional screenshots.

Every Layer Must Earn Its Place

LkSvn — Sat, 01 Aug 2026 01:26:50 +0000

While starting a practical transition into C# and ASP.NET Core, I found that a
simple endpoint was becoming harder to understand as each concept introduced a
new structural element: endpoint, service, repository, interface, DTO, and
result type.

Each tool can solve a real problem. The problem is adopting the complete stack
before those problems exist.

My working rule is now incremental:

Start with the smallest endpoint that expresses the behavior.
Extract application behavior when HTTP and business rules begin changing for different reasons.
Add a persistence boundary when it protects the application from meaningful storage concerns or supports valuable test isolation.
Add interfaces when multiple implementations or a genuine boundary exists.

This is not anti-architecture. It is architecture proportional to the system.
A modular monolith with clear responsibilities can be safer than a deeply
layered or distributed design whose abstractions mostly forward calls.

Done Is Finally Better Than Perfect

LkSvn — Tue, 28 Jul 2026 20:51:39 +0000

I finally shipped the first version of my freelance landing page.

The funny part?

I spent weeks thinking I had a design problem.
I didn't.
I had a content problem.
The layout is good enough.
The copy is good enough.
The CSS is good enough.

What the page really needs now is more real projects.

Instead of redesigning it again, I'm going to spend my time replacing concept work with actual client work as it comes in.

Sometimes the next version isn't another refactor.

It's simply experience.

🔗 https://lksvn.com.br/freelance/

Omitted Is Not Empty: Modeling Nullable Partial Updates

LkSvn — Mon, 27 Jul 2026 19:19:44 +0000

While adding Job Opportunity editing to my Candidate Tracker, one optional description produced three different behaviors:

omit the property to preserve the stored value;
provide a string to replace it;
provide null to clear it.

The first version mixed undefined and null across the domain, Prisma adapter, application service, and form action. That made clearing a value ambiguous.

The final convention uses string | null for persisted domain entities and optional properties for partial update commands. PostgreSQL NULL, Prisma null, and the domain now use the same absence representation. At the update boundary, omission still means “do not change.”

The broader lesson is that update types describe commands and state transitions. They should distinguish every behavior the application needs instead of merely reusing an entity shape without considering omission.

Tests Should Buy Confidence, Not Become the Feature

LkSvn — Fri, 24 Jul 2026 20:28:35 +0000

While implementing the Job Opportunity creation workflow in my Candidate Tracker, I reached an uncomfortable point: the application-service tests felt harder to understand than the feature itself.

The production workflow was small:

Validate and normalize the submitted input.
Confirm that the selected Company exists.
Create the Job Opportunity.

The tests introduced much more vocabulary and setup: fixtures, fakes, spies, mocks, controlled failures, and assertions that certain repository methods were never called.

That complexity is not automatically a problem. A test must construct the world in which a behavior runs. However, it made me reconsider what each test was actually buying.

The tests I kept

I kept three application-service cases:

valid input is normalized and created;
invalid input stops before persistence;
a missing Company does not create an orphan opportunity.

These cases protect business decisions. If any of them breaks, the application can accept invalid data or violate an important relationship.

The tests I did not add

The service also forwards failures returned by repositories. I could mock every repository method and test every forwarding branch, but those tests would mostly prove that:

if (!result.success) return result;

{data-source-line="157"}

returns the same result it received.

That behavior is already constrained by TypeScript, while real PostgreSQL integration tests verify persistence behavior. The complete browser workflow was also checked manually.

Adding more mocks would increase the test count, but not necessarily my confidence.

Choosing the right testing level

My current rule is:

unit-test business rules and meaningful decisions;
integration-test actual persistence behavior;
verify the complete user workflow;
add regression tests when real bugs reveal a missing case;
do not optimize for test count or branch coverage alone.

This is not an argument against testing. It is an argument for making every test justify its maintenance cost.

Tests should reduce the fear of changing code. When the setup becomes harder to understand than the protected behavior, the testing level or scope may need simplification—not necessarily the feature.

A Prisma Schema Change Has Three Lifecycles

LkSvn — Wed, 22 Jul 2026 21:47:40 +0000

One valid PostgreSQL row refused to appear on my Next.js page.

The relationship was correct, the SQL join returned the row, and the repository compiled. At runtime, however, Prisma returned an undefined jobOpportunity relation.

The stale layer was not the database

I had changed the Prisma schema while the development server was running. That change involved three independent lifecycles:

prisma migrate updates the database.
prisma generate updates the TypeScript client.
Restarting Next.js replaces the stale generated client held by the running process.

The first two steps were complete. The third was not.

Coming from PHP and CodeIgniter, this is an important mental-model shift. A request-scoped PHP application normally loads changed code on the next request. A long-running Node.js process can keep generated code and development caches alive.

Prisma provides valuable type safety, but it does not remove complexity—it relocates it.

My new debugging rule is simple:

Application edit → trust hot reload.
Prisma model change → migrate, generate, restart.
Suspicious stale behavior → clear the framework cache and restart.

Before rewriting a correct query, identify which layer is stale.

Not Every Productive Day Looks Like Writing Code

LkSvn — Wed, 22 Jul 2026 01:11:55 +0000

Sometimes the most valuable work doesn't produce a single commit.

Today was one of those days.

I didn't implement a new feature in my TypeScript project.

I didn't learn a new framework.

I didn't even spend much time writing code.

At first, that felt unproductive.

But looking back, I realized I spent the day investing in something that will make future work easier.

Building the Infrastructure Around Development

The first thing I worked on was updating my fresh-install script.

Every time I format my machine or switch computers, I find myself repeating the same setup steps. Automating those tasks doesn't make my GitHub contribution graph greener, but it saves hours every time I need a fresh environment.

Then I spent several hours reorganizing my personal knowledge base.

I reviewed old notes, connected documentation from personal projects, organized topics by area, improved tagging, and turned scattered information into something I can actually navigate.

It wasn't exciting.

It wasn't glamorous.

But it felt necessary.

We Optimize Applications...

As developers, we spend a lot of time reducing friction for users.

We optimize APIs.

We improve application performance.

We refactor code to make future changes easier.

But we rarely apply the same mindset to ourselves.

Why should finding a note from six months ago take longer than searching production logs?

Why should I rediscover the same solution every few months?

Knowledge Compounds

One thing I've been realizing while working on my Candidate Tracker project is that the code is only part of the learning process.

The architecture decisions.

The trade-offs.

The mistakes.

The reasons why I chose one approach instead of another.

Those are often more valuable than the final implementation.

If I don't capture them somewhere, I'll eventually lose them.

A personal knowledge base isn't just documentation.

It's an extension of memory.

Invisible Progress

It's easy to measure productivity by commits.

It's much harder to measure things like:

Better documentation
Faster onboarding to your own projects
Easier environment setup
Less context switching
Less time searching for information

These improvements don't show up on GitHub.

But they compound over time.

Final Thoughts

Today reminded me that software engineering isn't only about writing code.

Sometimes the best investment you can make is reducing the friction of tomorrow's work.

The results may not be visible immediately.

But future you will definitely notice.

I'd love to know:

What's one "behind the scenes" improvement that has made the biggest difference in your daily workflow?

Architecture starts paying rent when a user workflow reaches it

LkSvn — Mon, 20 Jul 2026 20:47:42 +0000

My TypeScript Candidate Tracker passed 100 tests before it had a page I could actually use.

The repository contracts, Result types, validation services, Prisma adapter, and PostgreSQL integration all had value—but the project still felt like it was walking in place.

Today I changed direction and connected one complete Company workflow to Next.js:

FormData from the browser

runtime shape validation
business validation
application service
repository
Prisma
PostgreSQL
refreshed Server Component

The same application now lists, creates, displays, and edits real persisted Companies.

Several earlier decisions finally became concrete:

browser validation improves UX but cannot protect the server
successful database absence becomes an explicit not-found outcome
Server Actions are real public input boundaries
a shared Prisma client matters under development hot reload
database-generated UUIDs work beyond Prisma Client, including Studio and raw SQL

The lesson was not that architecture is useless. It was that architecture needs a consumer.

Once a real user workflow crossed every layer, the abstractions stopped feeling theoretical and started explaining their cost.

Stronger application-layer types remove impossible states

LkSvn — Sat, 18 Jul 2026 17:00:00 +0000

Today I completed a small Company write vertical slice in TypeScript, from business validation to PostgreSQL persistence.

One detail clarified why application services are more than repository wrappers.

The repository update returns Company | undefined. That makes sense at the data layer: the query can succeed while the requested row does not exist.

But the application service translates undefined into an explicit not-found result.

After that translation, keeping Company | undefined in the successful return type would force every caller to handle a state the service has made impossible.

So the application contract returns either:

success with a Company
validation failure
not-found failure
repository failure

The type now describes the use-case guarantee instead of leaking the repository's lower-level uncertainty.

The practical lesson:

good TypeScript types do more than prevent syntax mistakes. They help make invalid or impossible application states unrepresentable.

A passing test can still prove nothing

LkSvn — Fri, 17 Jul 2026 01:42:52 +0000

Today I had a PostgreSQL integration test passing for the wrong reason.

The test was supposed to prove that updating a missing Company returned a successful "not found" result.

I passed an id like: company-missing

But the database column was a UUID.

PostgreSQL rejected the malformed value before Prisma could determine whether the Company existed. The repository returned a failure instead of the expected missing-record outcome.

The test still passed.

Why?

Its assertion was inside a conditional success branch. Because the result was a failure, the branch never ran. The test completed with no failing assertion.

The correction was small but important:

generate a valid UUID that was never inserted
assert the complete Result object directly
expect success with undefined data

That made the test exercise Prisma's real missing-record behavior instead of an invalid-input error.

The lesson

A green test is not automatically evidence.

Check that the intended branch was reached and that the assertion could actually fail.

Strong TypeScript contracts turn refactors into checklists

LkSvn — Wed, 15 Jul 2026 15:10:00 +0000

Today a TypeScript refactor produced 15 compiler errors.

It looked worse than it was.

My Candidate Tracker used a type called AsyncResult<T> with errors represented only as strings.

While adding a real PostgreSQL repository, two design problems became clear:

the result itself was not asynchronous; the surrounding Promise was
an error string discarded its category and original cause I changed the contract to Result<T, E> and introduced a typed RepositoryError.

The compiler immediately identified every repository, dashboard function, test, and callback that still depended on the old contract.

Most of the 15 errors were not separate problems. They were downstream symptoms of a few outdated type definitions.

Once those source contracts were corrected, the remaining errors disappeared and all tests passed again.

The lesson was practical:

Strong types do more than prevent mistakes while writing code. They make architectural changes searchable, explicit, and finite.