Home / journal / 2026-06-26

Daily Journal: 2026-06-26

Wins

Backend Residency

  • Created AGENTS.md, establishing the permanent operating manual for AI-assisted learning.
  • Defined a coaching philosophy centered on maximizing long-term engineering skill acquisition while minimizing unnecessary friction
  • Clearly established the boundaries of AI assistance, including the Assistance Hierarchy and Code Generation Policy.
  • Introduced three operational modes:
    • Build Mode for implementation
    • Practice Mode for isolated skill development
    • Interview Mode for communication and interview readiness
  • Defined a continuous learning loop where implementation reveals weakness, practice addresses them, and interview sessions validate understanding.

BiteTrack API

  • Created the bitetrack-api repository
  • Initialized the project with UV
  • Added the initial development tooling:
    • FastAPI
    • Ruff
    • Pyright
    • Pytest
  • Added an MIT license
  • Configured .envrc for local development
  • Created an initial .gitignore covering secrets, virtual environments, caches and build artifacts.
  • Added a minimal docker-compose.yml with a PostgreSQL service
  • Successfully configured direnv and verified that the development environment loads automatically.
  • Successfully built and started the PostgreSQL container

Mistakes and Lessons Learned

Docker Volume Mapping

Initially mounted the PostgreSQL data volume to:

/var/lib/bitetrack/data

This was causing data to be cleared upon container restart because the official PostgreSQL container image stores database files under:

/var/lib/postgresql/data

The volume must target PostgreSQL's expected data directory unless the container itself is explicitly reconfigured

Lesson Learned: Persistent volumes must be attached to the directory actually used by the application, not to an arbitrary project specific path.

Understanding .envrc

Initially, I treated .envrc like a regular .env file, unaware that .envrc is executed as a shell script.

Therefore, my initial .envrc looked like: 

# .envrc
source ".venv/bin/activate"

POSTGRES_USER="username"
POSTGRES_PASSWORD="password"
POSTGRES_DB="db_name"

Of course, the virtual environment was loading with no issues, but the environment variables were missing from the project's PATH, causing the container to start lacking the key variable environments: 

bitetrack_pgdb  | Error: Database is uninitialized and superuser password is not specified.
bitetrack_pgdb  |        You must specify POSTGRES_PASSWORD to a non-empty value for the
bitetrack_pgdb  |        superuser. For example, "-e POSTGRES_PASSWORD=password" on "docker run".
bitetrack_pgdb  |
bitetrack_pgdb  |        You may also use "POSTGRES_HOST_AUTH_METHOD=trust" to allow all
bitetrack_pgdb  |        connections without a password. This is *not* recommended.

Lessons learned:

Variables must be exported: direnv evaluates shell code; environment variables only become available to child processes when exported.

The corrected .envrc looks like this: 

# .envrc
source ".venv/bin/activate"
export POSTGRES_USER=username
export POSTGRES_PASSWORD=password
export POSTGRES_DB=db_name

Questions

  • With NixOS already providing direnv, when does it become necessary or advantageous to introduce devShells? which responsibilities belong to each?
    • Answered in [[environments]]
  • I attempted to namespace the PostgreSQL volume because I expected multiple databases to coexist on this machine. Is naming Docker volumes per application considered good practice? What are the recommended conventions for avoiding collisions while still using PostgreSQL's default data directory?
    • Answered in:[[docker#Docker & Containerization Notes#Docker Volume names]]

Reflection

Today's work was heavily focused on documentation, tooling and process design.
Normally I would consider that a warning sign, but in this case, I believe it was a worthwhile investment because these decisions establish the workflow that will guide the remainder of the learning journey.

The important constraint is that this phase is now complete. Moving forward, my efforts should primarily focused on generate engineering experience rather than additional process.

Tomorrow

Primary Objective:
- Begin implementing Milestone 0 of BiteTrack.
Secondary objectives:
- Complete one short Python practice exercise
- Finish one mock interview focused on today's implementation work or Python fundamentals.

Important: No additional changes to the AGENTS.md or the backend-residency structure unless implementation exposes a genuine deficiency.