DEV Community: luis-botelho

TDD Saved Me From a Database I Didn't Have Yet

luis-botelho — Sun, 20 Sep 2026 02:13:20 +0000

The Hook

I used to think TDD was mostly ceremony for code that's obviously going to work anyway. Building the risk-scoring piece of Web3 Shield this week talked me out of that, and I want to show the actual code that did it — not just claim it happened.

The Rule Worth Isolating

The heuristic is small on purpose: look at a transaction's function signature, decide how risky it is.

def calculate_risk_score(signature: str) -> int:
    # 0x095ea7b3 = 'approve' — lets another contract spend your tokens.
    # Very high risk, heavily used in phishing and wallet drains.
    if signature == "0x095ea7b3":
        return 90

    # 0xa9059cbb = 'transfer' — standard ERC-20 transfer.
    # Moderate risk, common transaction.
    elif signature == "0xa9059cbb":
        return 30

    # Anything else, unknown contract, or native transfer.
    return 10

And the tests that came first:

def test_calculate_risk_score_approve_perigoso():
    score = calculate_risk_score("0x095ea7b3")
    assert score == 90

def test_calculate_risk_score_transferencia_comum():
    score = calculate_risk_score("0xa9059cbb")
    assert score == 30

def test_calculate_risk_score_desconhecido():
    score = calculate_risk_score("0x00000000")
    assert score == 10

Nothing here touches a database, a network call, or Docker. That's the part that clicked for me: I could run and trust these tests before Postgres, before the polling loop, before any of the plumbing existed. The business rule is a pure function, and testing it in isolation is what "the domain doesn't know about infrastructure" actually feels like, not just a phrase from a Clean Architecture talk.

The Plumbing Around It

Once the rule was trustworthy, wiring it up was almost anticlimactic — which, I'm starting to think, is the point:

def main():
    repo = PostgresRepository()
    while True:
        unprocessed = repo.get_unprocessed_transactions()
        for tx in unprocessed:
            score = calculate_risk_score(tx['function_signature'])
            repo.save_risk_analysis(tx['tx_hash'], score)
        time.sleep(3)

def get_unprocessed_transactions(self):
    query = """
        SELECT r.tx_hash, r.function_signature 
        FROM raw_transactions r
        LEFT JOIN risk_analysis a ON r.tx_hash = a.tx_hash
        WHERE a.tx_hash IS NULL;
    """
    with self.conn.cursor(cursor_factory=RealDictCursor) as cursor:
        cursor.execute(query)
        return cursor.fetchall()

A LEFT JOIN ... WHERE a.tx_hash IS NULL is the whole "find what I haven't processed yet" logic — no separate status column to keep in sync, no queue system. Postgres already knows what's missing.

Prisma Introspecting a Database It Didn't Create

The Node API layer never wrote its own schema. Go and an init.sql file had already created the tables, so I ran:

npx prisma db pull

and Prisma read the existing Postgres schema and generated matching TypeScript models automatically:

model raw_transactions {
  id                 Int       @id @default(autoincrement())
  tx_hash            String    @unique @db.VarChar(66)
  to_address         String?   @db.VarChar(42)
  function_signature String?   @db.VarChar(10)
  risk_analysis      risk_analysis?
}

model risk_analysis {
  id               Int       @id @default(autoincrement())
  tx_hash          String    @unique @db.VarChar(66)
  risk_score       Int
  raw_transactions raw_transactions @relation(fields: [tx_hash], references: [tx_hash])
}

That relation is what makes the wallet audit endpoint a single query instead of two round trips and manual stitching:

fastify.get('/wallet/:address/risk', async (request, reply) => {
  const { address } = request.params as { address: string };

  const interactions = await prisma.raw_transactions.findMany({
    where: { to_address: { equals: address, mode: 'insensitive' } },
    include: { risk_analysis: true },
  });

  const hasCriticalRisk = interactions.some(
    (tx) => tx.risk_analysis && tx.risk_analysis.risk_score >= 80
  );

  return reply.send({
    success: true,
    wallet: address,
    status: hasCriticalRisk ? 'CRITICAL_RISK' : 'MODERATE_RISK',
    total_interactions: interactions.length,
  });
});

include: { risk_analysis: true } is doing a JOIN I didn't have to write by hand.

Two Bugs That Cost Real Time

The CLI that wasn't the CLI. npx prisma started failing with confusing errors — it turned out an experimental package, @prisma/composer, had intercepted the global prisma command. Fixed by installing Prisma as a local dev dependency (npm install prisma@latest --save-dev) and calling it explicitly from package.json scripts instead of trusting global resolution.

Secrets in the wrong place. Early on, database credentials were hardcoded directly in the Go source. I moved them into .env files loaded via godotenv, and turned the schema itself into a versioned init.sql, mounted into the Postgres container through Docker Compose — so the database structure is something reviewable in a PR, not something typed once into a terminal and forgotten.

The Gap I'm Leaving In on Purpose

Right now, raw_transactions only stores to_address — the contract being called. That's enough to flag a dangerous contract, but not enough to say a specific wallet is at risk, since it never records who's calling. I know this is a gap. I'm writing it down instead of quietly fixing it off-screen, because the next real decision — adding from_address to the Go layer vs. building webhooks first — is one I haven't made yet.

Let's Discuss! 👇

If you've had a CLI tool silently hijacked by another package before (like the @prisma/composer conflict here) — what was the debugging path that actually got you to the real cause?

python #typescript #tdd #postgresql

The Moment Go's select Statement Finally Made Sense to Me

luis-botelho — Tue, 15 Sep 2026 05:06:25 +0000

The Hook

"Go is good at concurrency" is a sentence I'd read a dozen times before it meant anything to me. This week, building the one real piece of Web3 Shield that exists so far — a Go worker that listens to a blockchain in real time — it finally clicked. Sharing the moment, not a lecture.

This is a learning-notes post, part of a series where I'm figuring out this project's architecture mostly in public, including the parts I get wrong.

What I Was Actually Trying to Do

Listen to a blockchain node, react the instant a new block is mined, and also notice if the connection itself drops — all without a pile of manual thread management I definitely don't know how to do well yet.

The Piece That Clicked

headers := make(chan *types.Header)
sub, err := client.SubscribeNewHead(context.Background(), headers)
if err != nil {
    log.Fatal(err)
}

SubscribeNewHead hands back a channel. A new block header shows up on it whenever one's mined — no polling loop asking "anything yet?" on repeat.

for {
    select {
    case err := <-sub.Err():
        log.Fatal("🚨 Erro na inscrição:", err)
    case header := <-headers:
        block, err := client.BlockByHash(context.Background(), header.Hash())
        if err != nil {
            continue
        }
        // ...process block
    }
}

One goroutine. One select. Two channels. It waits until either has something, reacts, loops. I'd seen this pattern in tutorials before and nodded along without really getting why it mattered. Watching it hold a real WebSocket connection open, live, was different — I could actually feel what "non-blocking" meant instead of just repeating the word.

The Reasoning I'm Testing (Not Proving Yet)

I learned that a goroutine blocked on a channel costs kilobytes, not a whole OS thread. My working theory is that this means listening to more chains later is just "spawn more goroutines," not "redesign the whole thing." I like that idea a lot. I also haven't tested it at any real scale, so take it as a hypothesis I'm holding, not a claim I've proven.

What I Kept Out of This Piece on Purpose

This worker doesn't judge anything — no "this looks suspicious," no scoring. It captures three fields (hash, destination, function signature) and writes them to Postgres:

insertQuery := `
INSERT INTO raw_transactions (tx_hash, to_address, function_signature) 
VALUES ($1, $2, $3) 
ON CONFLICT (tx_hash) DO NOTHING;`

I don't know enough yet to build the "is this suspicious" logic well, so I'm deliberately not trying to right now. That part comes later, once I've learned more.

What's Next

Trying to get a Python service reading this raw data and attempting an actual risk score — where I find out how much of the architecture reasoning from the last post actually survives being built.

Let's Discuss! 👇

If you remember the moment something about Go's concurrency model actually clicked for you (goroutines, channels, select, whatever it was) — what was the thing that made it click? Genuinely curious what other people's version of this moment looked like.

golang #beginners #learninpublic #blockchain

I Listened to a Blockchain in Real Time for the First Time. Here's What I Learned.

luis-botelho — Tue, 15 Sep 2026 05:04:00 +0000

The Hook

I'd read about blockchains plenty. Reading an explorer, querying past data — that felt familiar, like querying any other database. Subscribing to a live node and reacting to blocks as they happen was a completely different feeling, and I didn't fully get why until I built it.

This week, for Web3 Shield (an open-source project I'm building to practice backend and security fundamentals — not because I'm an expert in any of this), I got a first real-time pipeline working. Sharing what I learned, not claiming I did it the "right" way.

Step 1: A Sandbox to Learn On

Before touching a real network, I forked Base (Coinbase's L2) locally using Anvil, from the Foundry toolchain. Real chain state, no gas cost, and — this mattered a lot for someone still learning — no fear of breaking anything real:

client, err := ethclient.Dial("ws://127.0.0.1:8545")
if err != nil {
    log.Fatalf("🚨 Erro ao conectar no Anvil: %v", err)
}

Step 2: Learning the Difference Between Asking and Listening

My first instinct, honestly, would've been to poll — ask "any new blocks?" on a timer. Turns out there's a better way: subscribe, and let the node push updates to you.

headers := make(chan *types.Header)
sub, err := client.SubscribeNewHead(context.Background(), headers)
if err != nil {
    log.Fatal(err)
}

SubscribeNewHead gives back a channel, and a new *types.Header shows up on it every time a block gets mined. No wasted requests, no guessing.

Step 3: The Part That Took Me a Minute to Understand

The subscription can die on you — node restarts, network hiccups — and I needed to know when that happens without spinning up a second thread just to watch for it. This is where Go's select finally clicked for me:

for {
    select {
    case err := <-sub.Err():
        log.Fatal("🚨 Erro na inscrição:", err)
    case header := <-headers:
        block, err := client.BlockByHash(context.Background(), header.Hash())
        if err != nil {
            continue
        }
        // ...process block
    }
}

One goroutine, one select, two channels. I'd read about this pattern before starting, but it didn't really mean anything until I watched it hold a live connection open and react to real blocks landing.

Step 4: Finding the Signal I Didn't Know Existed

For every transaction, I pull out the hash, the destination address, and something I'd never worked with before — the function signature: the first 4 bytes of the call data, which apparently tell you which contract function is being invoked, before the transaction is even confirmed.

toAddress := ""
if tx.To() != nil {
    toAddress = tx.To().Hex()
}

txData := tx.Data()
funcSig := "0x00000000" // plain ETH transfer, no calldata
if len(txData) >= 4 {
    funcSig = "0x" + hex.EncodeToString(txData[:4])
}

I didn't know this signal existed before this week. Now it's the whole reason this project might eventually be useful for something.

Step 5: Not Losing Data When Things Repeat

insertQuery := `
INSERT INTO raw_transactions (tx_hash, to_address, function_signature) 
VALUES ($1, $2, $3) 
ON CONFLICT (tx_hash) DO NOTHING;`

tx_hash is unique, and ON CONFLICT DO NOTHING means reprocessing a block twice isn't a crash — it's a no-op. Small thing, but it's the kind of detail I wouldn't have thought about before actually hitting it.

What I Deliberately Didn't Build Yet

No scoring, no "this looks suspicious" logic — this piece only captures data, correctly and without duplicating it. Deciding what's actually risky is a problem for a future post, once I've learned enough to attempt it.

What's Next

I'm going to try wiring in a Python service to read this raw data and actually attempt a risk score. I have no idea yet how much of my plan survives that.

Let's Discuss! 👇

If you've built something like this before — a live chain listener — what's the thing you wish someone had told you before you started? I'm early enough that I can still design around it.

golang #blockchain #beginners #learninpublic

I built a study operating system so AI would stop doing my learning for me

luis-botelho — Tue, 08 Sep 2026 10:04:33 +0000

AI disclosure: This article is based on my real study logs and workflow. I used AI to help research DEV's publishing format, organize the draft, and revise the English. The cover image was also AI-generated under my direction. I reviewed every technical claim and made the final editorial decisions.

AI made me faster at producing code. It did not automatically make me better at engineering.

That distinction became obvious when I looked at my GitHub: many repositories, several promising starts, and too few projects I could explain from database constraint to error response without reopening a chat.

So I stopped treating AI as a shortcut generator and designed a small study operating system around one rule:

An output only counts as learning if I can explain, reproduce, and verify the reasoning behind it.

This post describes the workflow as a system you can copy, modify, and run.

The architecture

My daily learning pipeline has four stages:

fundamentals -> academic theory -> market context -> real implementation

In practice:

math -> software engineering degree -> certification -> hiring challenge

Each stage has a specific responsibility.

Stage	Responsibility	Example
Fundamentals	Build the mental model	Sets, relations, Boolean logic, statistics
Academic theory	Name and structure the concept	Normalization, CPU architecture, distributed processing
Certification	Connect theory to industry vocabulary	SQL, cloud, project management, lakehouse
Hiring challenge	Produce evidence under constraints	API, tests, database schema, deployment

The important part is not the list. It is the dependency between stages.

On a database day, for example, I can move from mathematical relations to functional dependencies, from functional dependencies to normalization, and from normalization to constraints in PostgreSQL. One concept crosses four contexts instead of becoming four disconnected study sessions.

The scheduler: minimum, standard, and deep modes

Most study plans assume a constant amount of energy. Humans do not have one.

I use three execution modes:

type StudyMode = {
  duration: string;
  goal: string;
  evidence: string;
};

const modes: Record<"minimum" | "standard" | "deep", StudyMode> = {
  minimum: {
    duration: "10-15 minutes",
    goal: "keep continuity",
    evidence: "one recalled concept or answered question",
  },
  standard: {
    duration: "50-60 minutes",
    goal: "learn, close the source, and retrieve",
    evidence: "an explanation in my own words",
  },
  deep: {
    duration: "90 minutes",
    goal: "implement and integrate",
    evidence: "working code, tests, or deployment",
  },
};

The minimum mode is not a fake version of studying. It is fault tolerance.

If a bad day forces the system from standard to minimum, the process degrades gracefully instead of crashing to zero. Deep work remains important, but continuity protects the next session from the cost of a complete restart.

Tool boundaries: NotebookLM is memory, ChatGPT is dialogue

Using two AI tools without boundaries creates duplicated noise. I assign them different roles.

NotebookLM: source-grounded memory

I use it to organize:

college material;
course notes;
daily study sources;
summaries of where I stopped;
questions that still need review.

Its job is context recovery. When I return to a subject, I should not spend the first 20 minutes reconstructing the previous session.

ChatGPT: tutor and reviewer

I use ChatGPT to:

challenge my explanation;
generate a small exercise from a specific gap;
compare two architectural choices;
review code I already attempted;
help split an oversized problem;
identify claims that need documentation or tests.

Its job is interaction, not authority.

The AI protocol

The most useful file in each project may not be part of the application at all:

docs/ai-log.md

This is the template I use:

# AI Learning Log

## Problem
What behavior am I trying to implement or understand?

## My hypothesis before asking
What do I think the solution is? Where am I uncertain?

## AI suggestion
Summarize the proposed approach. Do not paste an entire conversation.

## What was wrong or incomplete?
Missing edge cases, invalid assumptions, outdated APIs, weak architecture, etc.

## Verification
- Documentation consulted:
- Test written:
- Manual experiment:
- Result:

## Retrieval check
Can I explain the solution without reopening the chat?

This changes the interaction. Before asking, I must state a hypothesis. After receiving an answer, I must find a way to falsify it.

The log also creates interview material. Instead of saying “I used AI to build this,” I can explain a concrete decision, a failed suggestion, the evidence that changed my mind, and the final trade-off.

A better prompt lifecycle

My old workflow looked like this:

task -> prompt -> generated code -> commit

The new workflow is:

task
  -> inspect the existing system
  -> write my hypothesis
  -> ask a bounded question
  -> compare the answer with docs
  -> write or adapt the code
  -> test the behavior
  -> explain it from memory
  -> commit

The extra steps feel slower locally. They are faster globally because they reduce copied mistakes, architectural drift, and the need to relearn the same concept.

Weekly routing

I route each weekday to a concept family:

Day	Core theme	Implementation target
Monday	Web and dynamic logic	DOM, events, async APIs
Tuesday	Databases	modeling, constraints, SQL
Wednesday	Computer architecture	memory, processing, I/O
Thursday	Data and distributed systems	batch, streaming, fault tolerance
Friday	Project engineering	scope, risk, estimates, Definition of Done
Saturday	Integration	90-minute build/test/deploy block
Sunday	Recovery	rest plus light weekly planning

The schedule is a routing table, not a prison. If one topic needs another week, it keeps its slot. I do not add a new active project to manufacture the feeling of progress.

One active challenge, explicit Definition of Done

My biggest operational change was freezing secondary projects.

I now work through real hiring challenges in sequence. Each challenge has a concept target and a Definition of Done.

For a menu and promotions API, for example, “done” does not mean that POST /products returned 201 once. It means:

business rules are explicit;
invalid input produces intentional errors;
database constraints protect invariants;
critical paths have tests;
setup is reproducible;
the README explains architecture and limitations;
I can defend the choices without the AI transcript.

This is where a study project begins to resemble engineering evidence.

Metrics that are harder to fake

Hours are easy to count and weak as a measure of learning. I track:

days the system stayed online;
concepts retrieved without the source;
bugs explained before they were fixed;
business rules protected by tests;
completed and deployable projects;
decisions recorded in the AI log.

Commits still matter, but a commit is an event. Understanding is a capability.

What I am testing next

This system is still an experiment. My current challenge sequence increases complexity deliberately:

schema-driven forms and DOM fundamentals;
TypeScript API, PostgreSQL, Docker, time-based promotion rules, and handwritten SQL;
React/Next.js filtering with URL synchronization;
architecture evolved through junior, mid-level, and senior releases;
transactions, concurrency, idempotency, and unstable external services.

The hypothesis is simple: if each project reuses old fundamentals while adding one hard constraint, the portfolio becomes evidence of progression instead of a gallery of unrelated demos.

The part AI cannot automate

AI can produce a plausible answer before I have formed a useful question. That is exactly why the workflow needs friction.

The goal is not to avoid AI. The goal is to make its contribution observable, bounded, and testable.

My current rule is:

AI may accelerate the feedback loop.
It may not silently own the reasoning.

If you are also learning with AI, try adding only one thing this week: write your hypothesis before your next prompt. The quality of the question changes, and so does the ownership of the answer.

Suggested discussion prompt: What evidence do you use to distinguish “I shipped it” from “I learned it” when AI helped write the code?

React + Go: What I Practiced Building a 'Simple' Mini Kanban

luis-botelho — Thu, 06 Aug 2026 21:15:07 +0000

The Hook

Not every challenge needs a database, a design system, or a microservice to be worth doing well. Veritas Consultoria Empresarial's Full Stack Challenge asked for a Mini Kanban — React frontend, Go backend, in-memory storage allowed. Simple scope, on purpose.

I used that room to practice the decisions that actually separate a demo from a delivery. Here's what's in the repo.

Isolating Storage Before You Need To

In-memory storage was explicitly allowed by the challenge. The lazy version is a global map somewhere in a handler file. Instead, every read and write goes through a MemoryTaskRepository:

type MemoryTaskRepository struct {
    mu    sync.RWMutex
    tasks map[string]domain.Task
}

func (r *MemoryTaskRepository) List() []domain.Task {
    r.mu.RLock()
    defer r.mu.RUnlock()

    tasks := make([]domain.Task, 0, len(r.tasks))
    for _, task := range r.tasks {
        tasks = append(tasks, task)
    }

    sort.SliceStable(tasks, func(i, j int) bool {
        return tasks[i].CreatedAt.Before(tasks[j].CreatedAt)
    })

    return tasks
}

func (r *MemoryTaskRepository) Save(task domain.Task) {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.tasks[task.ID] = task
}

Two things worth unpacking:

Why sync.RWMutex? Go's net/http server runs every request in its own goroutine, and plain maps aren't safe for concurrent access. RWMutex lets multiple reads happen in parallel (RLock) while writes get serialized (Lock) — so two simultaneous requests can't race and corrupt the map.

Why in-memory at all? Because it's behind a Repository interface, swapping the map for Postgres later means implementing one new struct with the same methods — List, FindByID, Save, Delete — not touching every handler in the codebase. The README documents this explicitly as a scope trade-off, data resets on restart, on purpose: it's scope, not an oversight.

Validation Lives With the Data, Not the Handler

func NewTask(id, title, description string, status TaskStatus) (*Task, error) {
    task := &Task{
        ID:          id,
        Title:       strings.TrimSpace(title),
        Description: strings.TrimSpace(description),
        Status:      status,
        CreatedAt:   time.Now().UTC(),
        UpdatedAt:   time.Now().UTC(),
    }

    if err := task.Validate(); err != nil {
        return nil, err
    }
    return task, nil
}

func (t *Task) Validate() error {
    t.Title = strings.TrimSpace(t.Title)
    t.Description = strings.TrimSpace(t.Description)

    if t.Title == "" {
        return ErrTaskTitleRequired
    }
    if !t.Status.IsValid() {
        return ErrInvalidTaskStatus
    }
    return nil
}

Both creation and update route through the same Validate(). Trim, required-field check, status check — one place, applied consistently no matter which code path touches a Task. On the HTTP side, the decoder adds its own layer: DisallowUnknownFields() rejects payloads with unexpected fields instead of silently ignoring them.

Two Paths, One Handler

Drag-and-drop feels like the whole feature — until you think about who can't use a mouse. Instead of treating keyboard/touch as an afterthought, TaskCard supports both from the start:

function handleKeyDown(event: KeyboardEvent<HTMLElement>) {
  if (event.key === "Enter" || event.key === " ") {
    event.preventDefault();
    onOpen(task);
  }
}

return (
  <article
    className="task-card"
    role="button"
    tabIndex={0}
    draggable
    aria-label={`Abrir tarefa: ${task.title}`}
    onClick={handleOpen}
    onKeyDown={handleKeyDown}
    onDragStart={handleDragStart}
    onDragEnd={handleDragEnd}
  >

Tab focuses the card, Enter/Space opens it, and the form inside lets you change status without ever touching drag-and-drop. Both paths — mouse drag and keyboard/form — end up calling the exact same handleUpdateTask in the useTasks hook. The update logic has no idea, and doesn't need to know, which path triggered it:

async function handleUpdateTask(id: string, input: UpdateTaskInput) {
  try {
    setIsSubmitting(true);
    const updatedTask = await updateTask(id, input);
    setTasks((currentTasks) =>
      currentTasks.map((task) => (task.id === id ? updatedTask : task)),
    );
    setSuccessMessage(getTaskUpdatedMessage(previousTask, updatedTask));
    return true;
  } catch (err) {
    setError(err instanceof Error ? err.message : "Não foi possível atualizar a tarefa.");
    return false;
  } finally {
    setIsSubmitting(false);
  }
}

What Shipped

✅ Full CRUD wired to a REST API
✅ Drag-and-drop between columns
✅ Validation on frontend and backend
✅ Loading, error, and feedback states
✅ Keyboard navigation + accessible alternative to drag-and-drop
✅ Backend organized into domain / handlers / repository
✅ Backend tests (repository + domain)
✅ One-command Docker Compose setup
✅ README, User Flow, and Data Flow documented with Mermaid diagrams

The Actual Takeaway

None of this — the Repository interface, the documented trade-offs, the accessible alternative — was required to pass a demo. A hardcoded array and a console.log would've worked for the happy path. What pushed these decisions was thinking about who reads this code next: whoever tests it, runs it, extends it, or has to explain it out loud in an interview.

Thanks to Veritas Consultoria Empresarial for turning a selection process into an actual practice exercise.

Repo: https://github.com/luis-botelho/desafio-fullstack-veritas

Let's Discuss! 👇

What's a "small" technical challenge where you ended up over-engineering (in a good way) just to practice a decision you don't get to make often?

golang #react #webdev #accessibility

Building LIA (Part 2 Implementation): Login, Session Storage, and a Real ADR-vs-Code Mismatch

luis-botelho — Fri, 24 Jul 2026 12:27:25 +0000

LIA is a hyperlocal employability platform...

LIA is a hyperlocal employability platform I'm building — fixed jobs, gigs, and a reputation layer for a small, isolated community, matched by proximity instead of routed through a national job board.

This post walks through the real implementation of login and session management (US-002): the backend endpoint, the JWT issuance, and how the frontend persists the session — plus a genuine architecture mismatch this code review turned up, straight from the repository.

The backend: validating credentials and issuing a JWT

The use case is intentionally thin. It finds the user, verifies the password with Argon2id, and returns only public fields:

// application/use-cases/auth/login.use-case.ts
import { verify } from 'argon2';
import { prisma } from '../../../infrastructure/database/prisma.js';

interface LoginRequest {
  email: string;
  password: string;
}

export class LoginUseCase {
  async execute({ email, password }: LoginRequest) {
    const user = await prisma.user.findUnique({
      where: { email },
    });

    if (!user) {
      throw new Error('Invalid credentials');
    }

    const passwordMatches = await verify(user.password, password);

    if (!passwordMatches) {
      throw new Error('Invalid credentials');
    }

    return {
      id: user.id,
      name: user.name,
      email: user.email,
    };
  }
}

Note the identical error message for "user not found" and "wrong password" — that's deliberate, not an oversight. Returning a different message for each would let an attacker enumerate which emails are registered.

// presentation/controllers/auth/login.controller.ts
export async function loginController(
  request: FastifyRequest<{ Body: LoginBody }>,
  reply: FastifyReply,
) {
  const { email, password } = request.body;
  const useCase = new LoginUseCase();

  try {
    const user = await useCase.execute({ email, password });

    const token = await reply.jwtSign(
      { sub: user.id, email: user.email },
      { expiresIn: process.env.JWT_EXPIRES_IN },
    );

    return reply.status(200).send({
      success: true,
      data: { token, user },
    });
  } catch (error) {
    if (error instanceof Error && error.message === 'Invalid credentials') {
      return reply.status(401).send({
        success: false,
        message: 'Invalid credentials',
      });
    }

    request.log.error(error);
    return reply.status(500).send({
      success: false,
      message: 'Internal server error',
    });
  }
}

The JWT plugin itself is a two-line Fastify plugin, registered globally:

// infrastructure/http/plugins/jwt.ts
import fp from 'fastify-plugin';
import jwt from '@fastify/jwt';

export default fp(async (app) => {
  await app.register(jwt, {
    secret: process.env.JWT_SECRET!,
  });
});

The frontend: where the actual decision gets made

This is the part worth slowing down on. Before this feature was built, an ADR in this same repo had already settled the session strategy: HTTP-only cookies, specifically so the frontend would never handle the raw token. Here's what got implemented instead.

The session is persisted in localStorage:

// services/auth-storage.ts
const STORAGE_KEY = "liahona.auth";

export function saveSession(data: unknown) {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
}

export function getSession() {
  const storage = localStorage.getItem(STORAGE_KEY);
  if (!storage) return null;
  return JSON.parse(storage);
}

export function clearSession() {
  localStorage.removeItem(STORAGE_KEY);
}

export { STORAGE_KEY };

And every request attaches that token manually, through an Axios interceptor, instead of relying on a cookie the browser would send automatically:

// services/api.ts
export const api = axios.create({
  baseURL: "http://localhost:3333",
  headers: { "Content-Type": "application/json" },
});

api.interceptors.request.use((config) => {
  const session = getSession();
  if (session?.token) {
    config.headers.Authorization = `Bearer ${session.token}`;
  }
  return config;
});

api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      clearSession();
      window.location.href = "/login";
    }
    return Promise.reject(error);
  },
);

This is a completely standard Bearer-token pattern — and it's also exactly the option the ADR had explicitly weighed against cookies and set aside, mainly because a token sitting in localStorage is readable by any script that runs on the page, which is a real (if often low-probability) XSS exposure. Nobody made a call to override the ADR; the implementation just drifted from it while being built step by step, and nobody re-checked the diff against the decision until this post.

One more artifact from that drift: there are currently two separate auth.service.ts files in the repo — an older one directly under services/, and a newer one under features/auth/services/ with a different response shape (ApiResponse<T> wrapper vs. a flat response):

// features/auth/services/auth.service.ts (current)
interface ApiResponse<T> {
  success: boolean;
  data: T;
}

export interface LoginResponse {
  token: string;
  user: { id: string; name: string; email: string };
}

export async function login(data: LoginRequest) {
  const response = await api.post<ApiResponse<LoginResponse>>("/login", data);
  return response.data.data;
}

Both files still exist. Only the second one is wired into the actual login flow today — the first is a leftover from an earlier pass that never got cleaned up. That's the kind of thing a quick pass of the review checklist from Part 1 catches immediately once you know to look for it.

Wiring it into React: AuthContext and the protected route

The session lives in a plain useState, hydrated once from localStorage on first render:

// contexts/auth-context.tsx
export function AuthProvider({ children }: AuthProviderProps) {
  const queryClient = useQueryClient();

  const [state, setState] = useState<{ user: AuthUser | null; token: string | null }>(() => {
    const session = getSession() as LoginData | null;
    return session
      ? { user: session.user, token: session.token }
      : { user: null, token: null };
  });

  function login(data: LoginData) {
    setState({ user: data.user, token: data.token });
    saveSession(data);
  }

  function logout() {
    clearSession();
    setState({ user: null, token: null });
    queryClient.clear();
  }

  const value = useMemo(
    () => ({ user: state.user, token: state.token, isAuthenticated: !!state.token, login, logout }),
    [state.user, state.token],
  );

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

And the protected route is about as small as this pattern gets:

// components/routes/protected-route.tsx
export function ProtectedRoute({ children }: ProtectedRouteProps) {
  const { isAuthenticated } = useAuth();

  if (!isAuthenticated) {
    return <Navigate to="/login" replace />;
  }

  return children;
}

What's next on this feature

The functional gap is small on paper and real in practice: no GET /me (so a page refresh trusts whatever is sitting in localStorage without asking the backend to confirm it's still valid), no /logout endpoint (logout today is purely client-side state clearing), and a session strategy that's one architecture decision removed from what's documented. None of that is a production blocker for an MVP with no sensitive data yet — but it's now a known, named gap instead of an invisible one, which is the entire value of writing this up.

If you've hit the same thing — a documented decision quietly drifting from the code while pairing with an AI assistant turn by turn — I'd like to hear how you catch it in your own workflow.

React + MVVM: The Entity I Didn't Create (and the State I Didn't Store)

luis-botelho — Fri, 24 Jul 2026 03:01:10 +0000

The Hook

Most architecture posts are about what you build. This one is about what I didn't build — and why skipping it was the actual engineering decision.

Epic 003 — Safety Checklists just shipped as v0.3.0 for SafeAnchor. Three complete modules now: Fleet, Maintenance, Safety Checklists — this is Part 2 of the series, picking up after Part 1's MVVM foundation. (v0.2.0/Maintenance shipped in between without its own post — quick recap below before we get to the interesting part.)

Quick recap of v0.2.0 (Maintenance Management): the same MVVM shape repeated for a second domain, the project's first real relationship (Vessel 1:N Maintenance), and its first aggregate endpoint — a dashboard returning { total, preventive, corrective, pending, completed } instead of a list, split into its own maintenanceDashboardService for a clean Single Responsibility boundary.

The Entity I Didn't Create

The checklist module needed templates, executions, and an inspection history per vessel. The "obvious" way to build history is a new Inspection entity: its own model, controller, service, maybe its own table down the line.

That's not what's in the repo. GET /vessels/:id/inspections points straight at the controller that already serves checklist executions:

js
// backend/src/routes/vesselRoutes.js
router.get("/:id/inspections", getChecklistExecutionsByVesselIdController);

And the "inspection history" logic is just a filter + sort on ChecklistExecution:

js
// backend/src/services/checklistExecutionService.js
export function getChecklistExecutionsByVesselId(vesselId) {
return checklistExecutions
.filter((execution) => execution.vesselId === vesselId)
.sort((a, b) => new Date(b.executedAt) - new Date(a.executedAt));
}

There's no inspectionModel.js, no inspectionController.js. "Inspection" is a name the product uses — under the hood it's the same ChecklistExecution record, viewed through a vessel-scoped, sorted lens. One fewer entity, one fewer set of endpoints, one fewer thing that can drift out of sync with the rest of the domain.

The State I Didn't Store

The inspection history screen needed sortable results — ascending or descending by date — without an extra fetch. The easy-but-wrong move is a second useState for the sorted list, kept in sync with a useEffect. Instead:

js
// viewmodels/useInspectionHistoryViewModel.js
export function useInspectionHistoryViewModel(vesselId) {
const [inspections, setInspections] = useState([]);
const [sortOrder, setSortOrder] = useState("desc");

// ...fetch logic sets inspections...

const orderedInspections = [...inspections].sort((a, b) => {
if (sortOrder === "desc") {
return new Date(b.executedAt) - new Date(a.executedAt);
}
return new Date(a.executedAt) - new Date(b.executedAt);
});

return { inspections, isLoading, error, orderedInspections, sortOrder, setSortOrder };
}

orderedInspections is recomputed on every render from state that already exists. No second useState, no synchronization useEffect, no way for the sorted list to disagree with the source data. If a value can be derived from state you already have, it isn't state.

What Shipped in v0.3.0
✅ Checklist Templates — reusable models, multiple items per template
✅ Checklist Execution — recorded against a specific vessel
✅ Inspection History — chronological, sortable, reusing ChecklistExecution
✅ Same MVVM shape (View → ViewModel → Service → Backend) as modules 1 and 2
Debt We're Naming on Purpose

Not everything gets solved by reuse. Still on the list: a dedicated preventive-maintenance history screen, a shared/reusable history component across modules (right now each one is its own page), pagination and filters, and — the big one — moving off in-memory mock data onto PostgreSQL + Prisma.

What's Next

Documentation Management — file storage instead of structured records, a genuinely different kind of problem from the last three epics.

Let's Discuss! 👇

Where's the line for you between "this deserves its own entity" and "this is just a view over something that already exists"? I'd like to hear where it's bitten people either way.

SafeAnchor #WebDev #React #Architecture #LearningInPublic #SoftwareEngineering

Building LIA (Part 1 Implementation): Clean Architecture and Argon2id in a Real Fastify + Prisma Registration Flow

luis-botelho — Wed, 15 Jul 2026 03:54:06 +0000

LIA is a hyperlocal employability platform I'm building for an isolated coastal district in Brazil — think fixed retail jobs, gigs, and a reputation layer, all matched by proximity instead of routed through a national job board.

This post is about the implementation: the actual folder structure, the real RegisterUserUseCase, and the Argon2id decision — pulled straight from the repository, not reconstructed from memory.

The Clean Architecture folder structure

LIA's backend is organized in four layers, and the direction of dependency is non-negotiable: outer layers depend on inner layers, never the other way around.

backend/src/
├── domain/
│ ├── entities/
│ └── repositories/ # interfaces only
├── application/
│ ├── dto/
│ └── use-cases/
├── infrastructure/
│ ├── database/
│ └── repositories/ # Prisma implementations
├── presentation/
│ ├── controllers/
│ └── routes/
└── shared/
└── errors/

Let's walk through the registration feature end to end, following that exact order.

Domain — the entity and the repository contract

The User entity is a plain interface. No decorators, no ORM annotations, no framework leaking in:

typescript// domain/entities/user.ts
export interface User {
id: string;
name: string;
email: string;
password: string;
createdAt: Date;
updatedAt: Date;
}

The repository is defined as a contract, not an implementation. The domain doesn't know — and doesn't care — whether it's backed by PostgreSQL, an in-memory map, or something else entirely:

typescript// domain/repositories/user.repository.ts
import { RegisterUserDTO } from '../../application/dto/register-user.dto.js';

export interface UserRepository {
create(data: RegisterUserDTO): Promise<{
id: string;
name: string;
email: string;
createdAt: Date;
updatedAt: Date;
}>;

findByEmail(email: string): Promise<{
id: string;
name: string;
email: string;
password: string;
createdAt: Date;
updatedAt: Date;
} | null>;
}

Notice create() never returns the password hash. That's not an accident — it's the same "strip credentials from every response payload" rule from the code review checklist in Part 1, enforced at the type level before it can ever leak.

Application — the use case

This is where the actual business rule lives: validate input, enforce uniqueness, hash the password, delegate persistence.

typescript// application/use-cases/register-user.use-case.ts
import { RegisterUserDTO } from '../dto/register-user.dto.js';
import { PrismaUserRepository } from '../../infrastructure/repositories/prisma-user.repository.js';
import argon2 from 'argon2';
import { AppError } from '../../shared/errors/app-error.js';

export class RegisterUserUseCase {
private readonly repository = new PrismaUserRepository();

async execute(data: RegisterUserDTO) {
if (!data.name.trim()) {
throw new AppError('Nome é obrigatório.', 400);
}

if (!data.email.trim()) {
  throw new AppError('E-mail é obrigatório.', 400);
}

if (!data.password.trim()) {
  throw new AppError('Senha é obrigatória.', 400);
}
const existingUser = await this.repository.findByEmail(data.email);

if (existingUser) {
  throw new AppError('E-mail já cadastrado.', 409);
}
const hashedPassword = await argon2.hash(data.password);

return this.repository.create({ ...data, password: hashedPassword });

}
}

A few things worth calling out for readers coming from an Express/MVC background:

AppError is a custom error class carrying an HTTP status code, but it's thrown from the application layer with zero knowledge of HTTP itself. The presentation layer decides how to translate it into a response — the use case just says "this is a 409."
Argon2id is called with library defaults here — argon2.hash(data.password). That's a legitimate MVP trade-off, and one this codebase is explicit about: [ADR-013] documents Argon2id as the algorithm decision (chosen over bcrypt for GPU-attack resistance per current OWASP guidance), while parameter tuning (memory cost, iterations) is left as a follow-up, not silently skipped.
Validation is intentionally basic (non-empty checks) at this stage of the project — this is the foundation sprint, not the final input-validation layer. Being upfront about that is part of the same "document the why" discipline from Part 1.

Infrastructure — the Prisma implementation

The repository interface gets implemented here, and only here. This is the piece that would get replaced if LIA ever moved off Prisma or off PostgreSQL — nothing above this layer would need to change.

typescript// infrastructure/repositories/prisma-user.repository.ts
import { UserRepository } from '../../domain/repositories/user.repository.js';
import { RegisterUserDTO } from '../../application/dto/register-user.dto.js';
import { prisma } from '../database/prisma.js';

export class PrismaUserRepository implements UserRepository {
async findByEmail(email: string) {
return prisma.user.findUnique({
where: {
email,
},
});
}

async create(data: RegisterUserDTO) {
return prisma.user.create({
data,
select: {
id: true,
name: true,
email: true,
createdAt: true,
updatedAt: true,
},
});
}
}

That select clause on create() is doing real work: it's a second, infrastructure-level guarantee that the password hash never makes it into the returned object — even if someone changes the domain contract upstream later.

Prisma itself is wired up through the driver adapter pattern introduced in Prisma 7, connecting directly against pg:

typescript// infrastructure/database/prisma.ts
import 'dotenv/config';
import { PrismaClient } from '../../generated/prisma/client.js';
import { PrismaPg } from '@prisma/adapter-pg';

const adapter = new PrismaPg({
connectionString: process.env.DATABASE_URL!,
});

export const prisma = new PrismaClient({ adapter });

This is a small but real example of what an ADR buys you in practice. [ADR-011] exists specifically because Prisma 7 changed its configuration conventions from earlier versions — without that ADR on record, a future "helpful" refactor could silently reintroduce a deprecated config pattern.

Presentation — controller, routes, and the server

The controller's only job is translating HTTP in and out. It has no business logic — it just calls the use case and maps AppError to a response:

typescript// presentation/controllers/register.controller.ts
import { FastifyReply, FastifyRequest } from 'fastify';
import { RegisterUserUseCase } from '../../application/use-cases/register-user.use-case.js';
import { AppError } from '../../shared/errors/app-error.js';
import { RegisterUserDTO } from '../../application/dto/register-user.dto.js';

export class RegisterController {
constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

async handle(request: FastifyRequest, reply: FastifyReply) {
try {
const body = request.body as RegisterUserDTO;

  const user = await this.registerUserUseCase.execute(body);

  return reply.status(201).send(user);
} catch (error) {
  if (error instanceof AppError) {
    return reply.status(error.statusCode).send({
      message: error.message,
    });
  }

  request.log.error(error);

  return reply.status(500).send({
    message: 'Internal Server Error',
  });
}

}
}

The use case is constructor-injected rather than instantiated inline inside handle() — that's what makes it possible to swap it for a mock in a controller test without touching Fastify at all.

Routing wires the controller to Fastify with the bare minimum of ceremony:

typescript// presentation/routes/register.routes.ts
import { FastifyInstance } from 'fastify';
import { RegisterController } from '../controllers/register.controller.js';
import { RegisterUserUseCase } from '../../application/use-cases/register-user.use-case.js';

const registerUserUseCase = new RegisterUserUseCase();
const controller = new RegisterController(registerUserUseCase);

export async function registerRoutes(app: FastifyInstance) {
app.post('/register', controller.handle.bind(controller));
}

And the Fastify instance itself — [ADR-012] — stays intentionally thin at this stage: CORS, a health check, and the registration routes:

typescript// presentation/server.ts
import Fastify from 'fastify';
import cors from '@fastify/cors';
import { registerRoutes } from './routes/register.routes.js';

export const app = Fastify({
logger: true,
});

await app.register(cors, {
origin: true, // dev only — opens CORS to any origin, e.g. localhost:5173
methods: ['GET', 'POST', 'PUT', 'DELETE'],
});

app.get('/health', async () => ({
status: 'ok',
}));

app.register(registerRoutes);

The shared error class tying it together

One small class does a lot of quiet work across every layer above:

typescript// shared/errors/app-error.ts
export class AppError extends Error {
constructor(
message: string,
public readonly statusCode = 400,
) {
super(message);
this.name = 'AppError';
}
}

It's what lets the use case say "this is a business rule violation, and here's the HTTP status that should map to it" without importing anything HTTP-related. The presentation layer is the only place that ever turns that status code into an actual response.

Why this is worth doing on a solo project

None of this is exotic engineering — it's the kind of layering most backend teams settle into eventually. The point of doing it explicitly, from the first registration endpoint, on a one-person project is that it turns architectural discipline into something enforceable instead of aspirational. The Definition of Done checklist behind this feature — password hashing validated at the persistence layer, credentials stripped from every response, centralized error handling — isn't a wishlist here. You can grep for it in this code and find it already true.

Questions about the trade-offs above — especially the Argon2id defaults or the validation approach — are welcome in the comments. This is an active build, and Part 2 will cover the frontend registration flow and where the current implementation gets hardened next.

React + MVVM: How I'm Organizing My Frontend for Scalability

luis-botelho — Mon, 13 Jul 2026 05:14:31 +0000

The Hook

Have you ever felt like your React components are doing too much? 😅 Fetching data, managing loading/error state, formatting it, AND rendering the UI — all in one file.

In my project, SafeAnchor (a vertical SaaS for maritime fleet management), I decided to move away from "vibe coding" and commit to a proper architecture: MVVM (Model-View-ViewModel).

![SafeAnchor MVVM data flow: View, ViewModel, Service and API]

Why MVVM?

For a junior developer in 2026, understanding system architecture — not just syntax — is a must-have skill. Here's how I decoupled my frontend logic into three layers, straight from apps/frontend/src/ in the repo:

src/
├── views/         # screens (JSX)
├── viewmodels/    # screen state + logic (custom hooks)
├── services/      # API communication
└── models/        # data shape

1. Services — pure API logic

Services don't care about buttons or spinners. They only care about talking to the API and shaping the response. This is the actual getVesselById from services/vesselService.js:

export async function getVesselById(id) {
  try {
    const response = await fetch(`${apiUrl}/vessels/${id}`);
    if (!response.ok) {
      throw new Error("Nao foi possivel carregar a embarcação.");
    }
    const data = await response.json();
    return { vessel: data, source: "api", error: false };
  } catch (error) {
    const vessel = fallbackVessels.find((v) => v.id === Number(id));
    return { vessel, source: "fallback", error: false };
  }
}

Look closely at the catch: if the request fails, the service returns a hardcoded local vessel instead of throwing. That's a deliberate resilience decision — more on it below.

2. Hooks as ViewModels — the brain

All state management — loading, fetching, error handling — lives here. This is what keeps the UI clean. From viewmodels/useVesselDetailsViewModel.js:

export function useVesselDetailsViewModel(id) {
  const [vessel, setVessel] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState("");

  useEffect(() => {
    async function loadVessel() {
      try {
        setIsLoading(true);
        const loaded = await getVesselById(id);
        setVessel(loaded.vessel);
      } catch (error) {
        setError("Não foi possível carregar a embarcação.");
      } finally {
        setIsLoading(false);
      }
    }
    loadVessel();
  }, [id]);

  return { vessel, isLoading, error, removeVessel };
}

3. Clean Views — just props in, JSX out

views/VesselDetailsPage.jsx only receives data via the hook. No fetching, no logic — which makes it much faster to test and maintain:

export default function VesselDetailsPage() {
  const { id } = useParams();
  const viewModel = useVesselDetailsViewModel(id);

  if (viewModel.isLoading) return <p>Carregando...</p>;
  if (viewModel.error) return <p>{viewModel.error}</p>;

  const vessel = viewModel.vessel;

  return (
    <main className="vessel-details">
      <h1 className="vessel-details__title">Embarcação</h1>
      <span className="vessel-details__value">{vessel.name}</span>
      {/* ... */}
    </main>
  );
}

Put together, the data flows one way: API → Service → ViewModel (Hook) → View (JSX) — no shortcuts, no components secretly reaching into the network layer.

The Fallback That Made Me Rethink "MVP Code"

![Resilience fallback flow when the backend is offline]

The nicest surprise re-reading my own code: vesselService.js already falls back to an in-memory vessel array when the Express backend is unreachable. The ViewModel and the View don't know (or care) which path ran — they just get { vessel, source, error }. One try/catch buys the whole app the ability to stay demoable even with the backend down.

Where SafeAnchor Actually Stands

✅ Epic 001 — Fleet Management Foundation: vessel listing, details, creation, editing, archiving — all shipped.
🔜 Epic 002 — Maintenance Management: up next.
🗺️ Later: Safety Checklists (with QR-code field access), Document Management, Maritime Academy.

My Tech Stack & Learning Process

Right now it's React + Vite on the frontend and Express on the backend, with a documented target migration to Next.js + TypeScript + Redux Toolkit as the app grows into a feature-based structure. To speed up my learning, I use NotebookLM to organize scattered concepts into structured technical guides — basically an AI-powered tutor for engineering fundamentals.

What's Next?

Refactoring CSS to the BEM standard
Hardening the fallback/error paths ahead of Maintenance Management
Building out Safety Checklists and QR-code field access

Let's Discuss! 👇

How do you handle state logic in your React apps? Do you prefer big all-in-one hooks, or a decentralized architecture like MVVM? Let me know in the comments!

SafeAnchor #WebDev #React #Architecture #LearningInPublic #SoftwareEngineering