DEV Community: luis-botelho

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