DEV Community: Renato Silva

Giving Your API a Voice: Sending Emails with Node.js and Nodemailer

Renato Silva — Mon, 04 May 2026 16:29:03 +0000

A great backend application doesn't just store data in a database; it communicates with the outside world. Whether it's a welcome email, a password reset, or a notification for a new feedback, knowing how to integrate an email service is a crucial skill for any developer.

In this article, I’ll show you how I integrated email notifications into my Feedback API using Nodemailer and the Provider Pattern.

The Goal

When a user submits feedback, the system should:

Validate the data.
Save it to the database.
Notify the administrator via email.

Architecture Matters: The Provider Pattern

Instead of hardcoding Nodemailer directly into my business logic, I used the Provider Pattern. This keeps the code decoupled. If I decide to switch from Nodemailer to AWS SES or SendGrid in the future, I only need to change one file.

1. Defining the Contract (Abstract Class)

First, we define what a MailProvider should do:

// src/providers/mail-provider/mail-provider.js
class MailProvider {
  async sendMail({ to, subject, body }) {
    throw new Error("Method 'sendMail' must be implemented.");
  }
}

module.exports = MailProvider;

2. Implementing with Nodemailer

Now, we create the actual implementation. We use environment variables to keep credentials safe.

// src/providers/mail-provider/nodemailer-provider.js
const nodemailer = require("nodemailer");
const { env } = require("../../env");

class NodemailerProvider {
  #transporter;

  constructor() {
    this.#transporter = nodemailer.createTransport({
      host: env.MAIL_HOST,
      port: env.MAIL_PORT,
      auth: {
        user: env.MAIL_USER,
        pass: env.MAIL_PASS,
      },
    });
  }

  async sendMail({ to, subject, body }) {
    await this.#transporter.sendMail({
      from: "Feedback Tool <no-reply@feedback.com>",
      to,
      subject,
      html: body,
    });
  }
}

module.exports = NodemailerProvider;

Integrating into the Use Case

Our Use Case (the business logic) doesn't care how the email is sent; it only knows that it has a mailProvider capable of sending one.

// src/use-cases/submit-feedback.js
async execute(request) {
  const parsedData = submitFeedbackSchema.parse(request);
  const { name, email, message } = parsedData;

  // Persisting data
  const feedback = await this.feedbackRepository.create({ name, email, message });

  // Sending notification
  const mailProvider = new NodemailerProvider();

  try {
    await mailProvider.sendMail({
      to: "Admin <admin@example.com>",
      subject: "New Feedback Received!",
      body: `<h1>New Feedback</h1><p>From: ${name}</p><p>${message}</p>`
    });
    console.log("✅ Email sent!");
  } catch (error) {
    console.error("❌ Email failed, but feedback was saved:", error);
  }

  return feedback;
}

Key Takeaways

1. Don't Let Email Failures Break Your App

I wrapped the sendMail call in a try/catch block. If the email service is down, the user's feedback is still saved in the database. The user shouldn't see an error 500 just because a notification failed.

2. Environment Validation

Always use a tool like Zod to validate your SMTP credentials (MAIL_HOST, MAIL_USER, etc.). If your credentials are missing, your app should fail early during startup, not when a user tries to send feedback.

3. Testing with Mailtrap

During development, I used Mailtrap. It acts as a "fake" SMTP server that catches your emails in a virtual inbox, so you don't accidentally spam real addresses while testing.

Conclusion

Adding an email service makes your application feel professional and alive. By using providers and dependency injection, you ensure your code remains maintainable and ready for scale.

How do you handle background tasks like emails in your projects? Let's talk in the comments!

Stop Trusting User Input: The Power of Schema Validation with Zod

Renato Silva — Sun, 03 May 2026 09:00:00 +0000

In web development, there is one golden rule: Never trust user input. Whether it is a login form, a search bar, or an environment variable, unvalidated data is a leading cause of bugs and security vulnerabilities.

For a long time, developers relied on manual if/else checks or complex Regex to validate data. But then came Zod.

The Problem: Manual Validation Hell

Imagine you have an endpoint that receives a user profile. Without a schema validator, your code becomes cluttered and hard to maintain:

// Manual validation is messy and error-prone
app.post("/profile", (request, reply) => {
  const { username, age, email } = request.body;

  // Manual type and existence checks
  if (!username || typeof username !== 'string') {
    return reply.status(400).send("Invalid username");
  }

  if (age && typeof age !== 'number') {
    return reply.status(400).send("Age must be a number");
  }

  if (!email || !email.includes('@')) {
    return reply.status(400).send("Invalid email format");
  }

  // This gets exponentially worse with more fields
});

This approach is hard to scale, easy to forget, and doesn't provide a clear contract of what the data should look like.

The Solution: Zod (The Developer's Shield)

Zod allows you to define a Schema a single source of truth for your data. If the incoming data doesn't match the schema, Zod catches it before it even touches your business logic.

1. Simple and Expressive Syntax

With Zod, the messy code above becomes clean and declarative:

const { z } = require('zod');

// Defining the blueprint for your data
const userSchema = z.object({
  username: z.string().min(3).max(20),
  email: z.string().email(),
  age: z.number().optional(),
});

// Single line to validate the entire object
const result = userSchema.safeParse(request.body);

if (!result.success) {
  // Returns a detailed, formatted error object to the client
  return reply.status(400).send(result.error.format());
}

2. Validating Environment Variables

One of the most powerful ways to use Zod is validating .env files. It ensures the server doesn't even start if a critical configuration (like a Database URL or a JWT Secret) is missing or malformed. This Fail-Fast strategy saves hours of debugging in production environments.

3. Coercion: Dealing with Input Strings

Data from HTML forms or URL parameters often arrives as strings, even if they represent numbers or dates. Zod's Coercion feature automatically converts these values during validation:

// Automatically converts the string "42" to the number 42
const schema = z.coerce.number();
const price = schema.parse("42"); 

console.log(typeof price); // "number"

Why Should You Care?

Fail-Fast: Catch errors at the very boundaries of your application.
Confidence: You can write your logic knowing exactly what shape your data has.
Developer Experience: Clear, automated error messages for both you and your API consumers.

Conclusion

Switching to schema-based validation with Zod isn't just about writing less code; it's about writing *predictable * code. It shifts your mindset from "I hope this data is correct" to "I know this data is correct."

I recently started implementing Zod in my professional projects, and the clarity it brings to the architecture is a point of no return.

Have you tried Zod yet, or are you still handling validations manually? Let's discuss in the comments! 👇

From "Student" API to Professional Grade: JWT Auth, Swagger, and Zod

Renato Silva — Sun, 26 Apr 2026 14:50:15 +0000

Building an API that works on your local machine is just the first step. But what separates a hobby project from a production-ready product? In today's post, I'll show how I transformed my feedback system into a robust, secure, and fully documented application.

🔐 1. The Digital "Key": Implementing JWT

Up until now, anyone who discovered my API URL could read every feedback ever submitted. In a real-world scenario, this is a critical privacy failure.

To solve this, I implemented JWT (JSON Web Token) using @fastify/jwt. The flow now works as follows:

The admin logs in with secure credentials.
The API generates a signed token.
This token must be sent in the header of every request to protected routes.

The game-changer here was using a Fastify decorator to create an authenticate hook. Now, protecting a route is as simple as adding a single line of code.

📖 2. Pro Swagger: Documentation that actually works

Documentation isn't enough; it needs to be useful. I was already using Swagger, but the challenge was: How do I test protected routes without leaving the browser?

I configured securitySchemes in Swagger to support the Bearer Auth pattern. The result? An "Authorize" button with a lock icon appeared at the top of the page. Now, I can log in through the interface itself, paste the token, and test private endpoints directly. Pure productivity.

🛡️ 3. Environment Shielding with Zod

A common mistake is an application failing in production because someone forgot to set a variable in the .env file.

To prevent this, I used Zod to create an environment "validator." I built a schema that checks:

If JWT_SECRET exists and is secure.
If DATABASE_URL is correct.
If PORT is actually a number.

If any of these variables are missing or wrong, the application crashes immediately at startup and tells you exactly what's wrong. This Fail-fast approach is a senior-level concept that brings real peace of mind.

// Validating our environment variables with Zod
const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().default(3000),
  JWT_SECRET: z.string().min(1, "JWT_SECRET is required"),
  DATABASE_URL: z.string().min(1, "DATABASE_URL is required"),
});

const _env = envSchema.safeParse(process.env);

if (_env.success === false) {
  console.error('❌ Invalid environment variables!', _env.error.format());
  process.exit(1); // Stop the app if config is wrong
}

🏗️ 4. Refactoring and Clean Architecture

As the API grew, the main file (app.js) started getting cluttered. I applied the "Separation of Concerns" principle:

Routes: Specific files to define paths and schemas.

Controllers: The bridge between HTTP and business logic.

App: Only orchestration and plugin registration.

This organization allowed the project to breathe and made maintenance much easier.

🚀 Pro-tip: Handling Git and .env

During the process, I learned (the hard way!) that adding .env to .gitignore after it's already tracked doesn't work. I had to clear the Git cache (git rm --cached .env) to ensure my secrets weren't stored in the commit history. Pro-tip: security is never too much!

Conclusion

My feedback API is no longer just code that saves data; it's an ecosystem with Testing (Vitest), Security (JWT), Interactive Docs (Swagger), and Continuous Deployment (Render).

Link to the project

What tools are you using to secure your APIs? Let’s talk in the comments! 👇

Sleeping Better at Night: Integration Tests and CI/CD for my Feedback API

Renato Silva — Thu, 23 Apr 2026 19:08:11 +0000

In my last post, I implemented schema validation to protect my domain. But as the project grows, checking every route manually with Insomnia or Postman becomes a bottleneck.

Today, I automated that process using Vitest and Supertest, and integrated it into my CI/CD pipeline.

The Goal: Real Confidence

I wanted to ensure that when I call the /feedbacks endpoint:

Valid data is correctly persisted in the database.
Invalid data is blocked by my Zod schemas with a proper 400 Bad Request.

The Setup: Environment Isolation

One golden rule of testing is: Never test on your production database. I adjusted my SqliteFeedbackRepository to accept a database path, allowing me to use a dedicated database.test.db during test execution. Using cross-env, I flag the environment so the app knows which "mode" to run in.

// src/app.js
const databasePath = process.env.NODE_ENV === "test" 
  ? "./database.test.db" 
  : "./database.db";

const repository = new SqliteFeedbackRepository(databasePath);

The Test Suite

Using Vitest, I created an E2E (End-to-End) test suite. It simulates real HTTP requests to the Fastify server and asserts the results.

// tests/submit-feedback.test.js
const { describe, it, expect, afterAll } = require('vitest');
const request = require('supertest');
const { app } = require('../app');

describe('Submit Feedback E2E', () => {
  it('should be able to submit a valid feedback', async () => {
    await app.ready();

    const response = await request(app.server)
      .post('/feedbacks')
      .send({
        name: "John Doe",
        email: "john@example.com",
        message: "This is a valid feedback message from integration test."
      });

    expect(response.status).toBe(201);
    expect(response.body).toHaveProperty('id');
  });

  it('should not be able to submit feedback with invalid email', async () => {
    await app.ready();

    const response = await request(app.server)
      .post('/feedbacks')
      .send({
        name: "John Doe",
        email: "invalid-email",
        message: "Valid message length"
      });

    expect(response.status).toBe(400);
  });
});

Continuous Integration (CI) with Render

Testing on your local machine is great, but enforcing tests before deployment is better. I updated my **Render **configuration to include the test suite in the build process.

By changing the Build Command to:

npm install && npm test

I’ve created a safety net: If a single test fails, the build fails. The broken version will never reach the users, and the previous stable version stays online. This is the essence of Continuous Integration.

Challenges Overcome: The Windows File Lock

If you are developing on Windows, you might encounter the resource busy or locked error when trying to delete the SQLite test file after the tests. This happens because the process still holds a lock on the file.

The fix? Properly closing the Fastify instance and the repository connection:

afterAll(async () => {
  await app.close();
  // Ensure the database connection is closed before unlinking the file
});

Why this matters

Now, every time I run git push, I get instant feedback. Automated tests are not a luxury; they are the foundation of professional software delivery. They give you the freedom to refactor and evolve your code without the fear of breaking what’s already working.

What's next? My API is now validated, tested, and protected by a CI/CD pipeline. To take it to the next level, I'll be looking into API Documentation with Swagger.

How do you handle testing in your deployment pipeline? Let's discuss in the comments!

Defending Your Domain: Schema Validation and Global Error Handling

Renato Silva — Mon, 20 Apr 2026 18:08:05 +0000

Defending Your Domain: Schema Validation and Global Error Handling

In my previous post, I shared how Clean Architecture allowed me to swap my database layer in minutes. But architecture isn't just about being able to change parts; it's about protecting your system from the outside world.

Today, I added a "bouncer" to my API: Schema Validation.

The Problem: Silent Failures

Without validation, your Use Case might receive an empty name, a fake email, or a message that is too short. This leads to corrupted data in your database and unexpected "Internal Server Errors" (500) that give no clue to the user about what went wrong.

The Solution: Zod + Global Error Handler

I chose Zod for schema validation because it's type-safe, extremely popular in the modern Node.js ecosystem, and integrates perfectly with JavaScript.

1. Defining the Contract

Instead of just accepting any object, I defined exactly what a Feedback should look like. This contract ensures that the data follows our business rules before any processing happens:

// src/use-cases/submit-feedback-validator.js
const { z } = require('zod');

const submitFeedbackSchema = z.object({
  name: z.string().min(3, "Name must be at least 3 characters long"),
  email: z.string().email("Invalid email address"),
  message: z.string().min(10, "Message must be at least 10 characters long"),
});

module.exports = { submitFeedbackSchema };

2. Future-Proof Error Handling

Libraries evolve fast. During implementation, I noticed that some built-in formatting methods like .format() or .flatten() were becoming deprecated or less flexible in the latest versions of Zod.

Instead of relying on unstable methods, I implemented a custom mapper to extract Zod's raw issues into a clean, developer-friendly response. By using a Global Error Handler in Fastify, I kept my routes clean and avoided repetitive try/catch blocks.

// src/server.js
fastify.setErrorHandler((error, request, reply) => {
  // Catching Zod validation errors
  if (error instanceof z.ZodError) {
    // Map raw issues into a clear field-to-message object
    const validationErrors = error.issues.reduce((acc, issue) => {
      const path = issue.path[0];
      acc[path] = issue.message;
      return acc;
    }, {});

    return reply.status(400).send({
      message: 'Validation failed.',
      errors: validationErrors,
    });
  }

  // Fallback for unexpected generic errors
  fastify.log.error(error);
  return reply.status(500).send({ message: 'Internal server error.' });
});

The Result: Better UX and Cleaner Code
Now, if a user sends invalid data, the API doesn't just crash or return a generic error. It responds with a 400 Bad Request and a clear explanation of what needs to be fixed:

{
  "message": "Validation failed.",
  "errors": {
    "email": "Invalid email address",
    "message": "Message must be at least 10 characters long"
  }
}

Key Takeaways:

Fail Fast: Stop invalid data at the door before it touches your business logic or your database.
Global Handling: Centralize your error logic. This makes your application easier to maintain and keeps your controllers focused on the "happy path".
Be Adaptable: When library methods get deprecated, don't be afraid to write your own mappers. It gives you more control and makes your code more resilient to library updates.

What's next? Now that the API is safe and resilient, the next step is to ensure it stays working as we add new features. My next post will be about Automated Integration Testing.

Have you ever struggled with "dirty data" in your database? Let's talk about it in the comments!

Architecture Saved My Project - Swapping an ORM for Pure SQL in Minutes

Renato Silva — Fri, 17 Apr 2026 19:02:47 +0000

In the world of software development, we are often told that Clean Architecture and SOLID principles are "over-engineering" for small projects. This week, I proved that theory wrong in the most practical way possible: I fired my ORM.

The Goal

I was building a Minimalist Feedback API. The plan was simple: use Prisma 6 with SQLite to persist data. I had already built my Core Domain (Entities) and Business Logic (Use Cases), keeping them isolated from external frameworks.

The Problem: When Tools Fight Back

As I moved to the infrastructure layer, I integrated Prisma 6. However, I ran into unexpected breaking changes and rigid configuration requirements—specifically the deprecation of certain URL properties in the schema files that were previously standard.

I had two choices:

Spend hours debugging a tool's internal configuration and fighting its "opinionated" setup.
Rely on my architecture to swap the tool entirely.

The Pivot: From Prisma to SQLite

Because I used the Repository Pattern, my Use Cases didn't know Prisma existed. They only knew about an abstract interface (or contract) called FeedbackRepository.

I decided to drop the ORM and implement a native SqliteFeedbackRepository using the standard sqlite3 driver.

1. The Repository Swap

I created a new implementation. Note how the logic remains focused only on data persistence, keeping the code clean and predictable:

// src/repositories/sqlite/sqlite-feedback-repository.js
const sqlite3 = require('sqlite3').verbose();
const { FeedbackRepository } = require('../feedback-repository');
const { randomUUID } = require('crypto');

// Connect to the database file
const db = new sqlite3.Database('./database.db');

class SqliteFeedbackRepository extends FeedbackRepository {
  /**
   * Persists a new feedback into the SQLite database
   */
  async create(data) {
    const id = randomUUID();
    const createdAt = new Date().toISOString();

    return new Promise((resolve, reject) => {
      const stmt = db.prepare(
        "INSERT INTO feedbacks (id, name, email, message, createdAt) VALUES (?, ?, ?, ?, ?)"
      );

      stmt.run(id, data.name, data.email, data.message, createdAt, (err) => {
        if (err) return reject(err);
        resolve({ id, ...data, createdAt });
      });

      stmt.finalize();
    });
  }

  /**
   * Retrieves all feedbacks from the database
   */
  async listAll() {
    return new Promise((resolve, reject) => {
      db.all("SELECT * FROM feedbacks ORDER BY createdAt DESC", [], (err, rows) => {
        if (err) return reject(err);
        resolve(rows);
      });
    });
  }
}

module.exports = { SqliteFeedbackRepository };

2. Dependency Injection in Action

In my server.js, the only change required was the import line. This is the Liskov Substitution Principle in the real world: the ability to replace an implementation with another without breaking the system.

// server.js
// Swapping the implementation is as simple as changing one line:
const { SqliteFeedbackRepository } = require('./repositories/sqlite/sqlite-feedback-repository');

// The rest of the setup remains identical!
const repository = new SqliteFeedbackRepository(); 
const submitFeedback = new SubmitFeedback(repository); // Use Case stays the same!

Why This Matters

If my database logic had been leaked into my Routes or Use Cases, a change like this would have forced me to rewrite a significant portion of the application.
Instead, it took me less than 10 minutes to pivot and have a fully working API again.

"Software architecture is the art of postponing decisions until you have more data. Or in this case, the art of making tools replaceable."

Key Takeaways

Don't be a hostage to your tools: If a library is causing more friction than value, be ready to replace it.
Isolate your Domain: Keep your business rules pure. They should not care if you are using an ORM, a Cloud DB, or a simple text file.
Pragmatism > Hype: Sometimes, "boring" technology like native SQL is exactly what you need to keep the project moving forward.

What about you?
Have you ever had to swap a core library mid-project? Let's discuss in the comments!

Check out the live API here: [https://https://minimalist-feedback-api.onrender.com/feedbacks]
(Note: Since this uses a free-tier ephemeral SQLite, the data resets on every deploy)

Final Thoughts

The biggest takeaway from this project was learning how to navigate version incompatibilities between technologies.

I saw firsthand how a solid architecture acts as a safety net. It turned what could have been a complete project restart into a series of manageable, easy-to-execute changes. Tools will always change, but good architecture ensures your business rules remain constant.

Beyond the Terminal: Why My Next Project is a Minimalist API

Renato Silva — Tue, 31 Mar 2026 17:53:05 +0000

Moving from local tools to network services. Let's talk about the architecture and challenges of building a professional Feedback API.

In my last posts, I shared the journey of building a CLI tool with a focus on simple architecture and automated testing. It was a success in terms of local automation.

But in the real world, software often needs to live on the network. It needs to be available for multiple users, persist data in a database, and handle concurrent requests.

That’s why my next project is a Minimalist Feedback API.

Here is why I’m building it and the "Senior-level" architectural choices I’m making.

The Use Case: A Universal Feedback Bridge

Many developers build beautiful static portfolios (using Astro, Next.js, or Hugo). But when it comes to adding a "Contact Me" or "Feedback" form, they hit a wall. They usually end up using a third-party paid service or a complex backend.

I’m building a lightweight, professional service that any static site can "talk to" to store messages and feedbacks.

The Architectural Shift: Clean Thinking

For this API, I’m not just throwing everything into a single server.js file. I’m introducing a simplified version of Clean Architecture.

1. Domain First, Framework Second

The "Business Logic" (what defines a valid feedback) should not depend on whether I'm using Express, Fastify, or even if I'm saving to MongoDB or PostgreSQL. The heart of the application will be isolated.

2. Validation as a First-Class Citizen

In a CLI, you control the input. In an API, the world is a chaotic place. I’ll be using Zod to ensure that only "clean" data enters my system. No validation, no entry.

3. Dependency Injection

I want to be able to test my logic without actually hitting a real database. By using Dependency Injection, I can swap a "Real Repository" for a "Mock Repository" in my tests instantly.

The Tech Stack for 2024/2025

To keep it modern and fast, I’ve chosen:

Node.js (Runtime)
Fastify: Faster and more modern than Express, with great TypeScript support.
SQLite + Prisma: For easy setup and type-safe database queries.
Jest: Because a professional API without tests is just a disaster waiting to happen.

What to Expect in the Next Posts

I’ll be documenting the Step-by-Step construction of this API.

Part 1: Designing the Domain and Entities.
Part 2: Setting up the HTTP Layer with Fastify.
Part 3: Database Integration and Migrations.
Part 4: Deploying with Docker/Cloud.

The goal isn't just to show you "how to code an API," but how to engineer a service that you’d be proud to show in a technical interview.

When you build an API, what is your biggest challenge? Authentication, Database design, or Deployment? Let's talk in the comments!

Stop Losing Your Documentation Images: Building a Practical CLI with Node.js

Renato Silva — Sun, 29 Mar 2026 15:58:22 +0000

External images in Markdown are a risk. I built a tool to solve this, focusing on simple architecture and testability.

Have you ever opened an old GitHub repository or a blog post only to find "broken image" icons everywhere?

It happens because we rely on external hosts. If the host goes down, your documentation dies.

In my last articles, I talked about Senior Mindset and Simple Architecture. Today, I’m putting those words into practice. I built MIL (Markdown Image Localizer): a CLI tool that finds remote images in your files, downloads them locally, and updates your links automatically.

Here is how I built it and why the "how" matters more than the code itself.

The Problem: The Fragility of the Web

We often use direct links for images in Markdown.

Dependency: If the source site changes, your image breaks.
Offline Access: You can't read your docs properly without internet.
Manual Labor: Downloading 20 images and updating 20 links manually is a waste of an engineer's time.

The Solution: MIL (Markdown Image Localizer)

I designed this tool following three core principles: Simplicity, Separation of Concerns, and Testability.

1. Simple Architecture

Instead of one giant file, I split the logic:

Parser: Pure logic to find URLs using Regex.
Downloader: Handles the I/O and HTTP requests.
Processor: Orchestrates the flow.
CLI: The entry point that talks to the user.

Why? Because if I want to turn this into a VS Code extension or a Web API tomorrow, the "Core" logic is already isolated.

2. Reliability through Testing

I didn't just "hope" the Regex worked. I implemented unit tests using Jest.
Before the first commit, I ensured that:

It ignores local images.
It handles duplicate URLs (no redundant downloads).
It returns empty results when no images exist.

"Code without tests is just a rumor."

See the Code

You can check the full source code, the folder structure, and the tests here:
👉 GitHub: markdown-image-localizer

How to run it:


bash
git clone [https://github.com/rj-dev/markdown-image-localizer](https://github.com/rj-dev/markdown-image-localizer)
npm install
node index.js your-file.md

The Art of Finishing: Why a Working "Simple" Project is Worth More Than a Perfect "Unfinished" One

Renato Silva — Sun, 29 Mar 2026 11:21:40 +0000

We all have a folder full of unfinished projects. Here is why finishing a small, simple tool is the best thing you can do for your career right now.

We’ve all been there.

You have a "revolutionary" idea for a SaaS. You spend three days picking the perfect CSS library. Two days setting up a complex Docker environment. Another week debating which state management tool to use.

And then... you stop.

The project stays in your /dev folder, gathering digital dust.

In the professional world, an unfinished "perfect" architecture is worth zero. A simple, working, and tested script that solves a real problem is worth everything.

As I prepare to launch my first practical projects here on DEV.to, I want to talk about the "Mindset of Done."

1. The "Scope Creep" Trap

The reason we don't finish things is that we let the scope grow too fast.
"It needs a login!"
"It needs a dashboard!"
"It needs to be mobile-responsive!"

The Senior Approach: Cut everything until you have the Minimum Viable Value. If you are building a CLI tool to rename files, just make it rename files. Everything else is a distraction for "Version 2."

2. Shipping is a Feature

Shipping—actually putting your code on GitHub with a README and a release—is a skill.

When you finish a project, you deal with the "unfun" parts that teach you the most:

Fixing that last annoying bug.
Writing the installation guide.
Setting up a simple CI/CD.

Recruiters don't look for "Genius in Progress." They look for "Engineers who Deliver."

3. The "90/10" Rule of Software

The first 90% of a project is fun. The last 10% (documentation, edge cases, final polish) is where the real engineering happens.

Most developers quit at 90%. If you can push through that last 10%, you are already ahead of the majority of the market.

How AI Helps You Cross the Finish Line

I use AI specifically to kill the "Last 10%" friction:

"The Boring Stuff": I ask AI to generate the package.json or requirements.txt based on my imports.
"README Architect": I describe my project and ask: "Write a clear 'How to Install' section for a beginner."
"Edge Case Hunter": I share my logic and ask: "What is the one thing that will make this crash when a user runs it for the first time?"

AI is my "Finishing Assistant." It handles the friction so I can focus on the core value.

Next Week: The First Commit

I’m done talking about theory.

Next week, I’ll be sharing the first repository of this series: A CLI Tool built with Simple Architecture. It’s not going to be a 10,000-line monster. It’s going to be a clean, tested, and finished piece of software that solves a specific problem. I’m doing this to show you that "Simple and Done" is the ultimate senior flex.

How many unfinished projects do you have in your folders right now? Let's be honest in the comments!

The Seniority Gap: Why Companies Hire Solutions, Not Just Syntax

Renato Silva — Thu, 19 Mar 2026 19:37:49 +0000

Technical skills are the baseline. But what actually gets you hired at high-level positions? Let's talk about the gap between coding and engineering.

I’ve interviewed hundreds of developers over the last decade.

Many of them were brilliant at solving LeetCode puzzles. They knew every obscure feature of their favorite language.

But when I asked them: "How would this code impact the business if the requirements changed tomorrow?"... they went silent.

This is the "Seniority Gap." Companies aren't looking for people who can just type code. They are looking for Engineers who can bridge the gap between a business problem and a sustainable technical solution.

Before I share my upcoming practical projects on GitHub, I want to talk about the three pillars that actually make a developer "Hirable" in today's market.

1. Context Over Syntax

A junior developer focuses on how to write a loop. A senior developer focuses on why that loop is necessary and if there’s a way to avoid it entirely.

When you show a project to a recruiter, don't just show the code. Explain the context:

What problem were you solving?
Why did you choose this specific approach over others?
What were the constraints?

2. The "Maintainability" Mindset

Code is written once, but read and modified a thousand times.

If your project is "clever" but impossible to understand six months later, it’s a liability, not an asset.

In the professional world, clarity is more valuable than brilliance. High-level developers write code that looks "obvious" because they’ve done the hard work of simplifying the complex.

3. Ownership and "The Big Picture"

Professional engineering is about taking ownership.

It’s about knowing how your code is deployed.
It’s about understanding if your API is slow for the end-user.
It’s about ensuring that your tests actually protect the business logic.

When you demonstrate that you care about the entire lifecycle of the software, you stop being a "task-taker" and start being a "partner."

How AI Helps You Close the Gap

AI is the ultimate tool for expanding your perspective beyond the code editor. Use it to simulate "Business Thinking":

"Roleplay as a Product Manager": Feed your project idea to the AI and ask: "What are the 3 biggest risks for this project from a business perspective?"
"Critique my Architecture": Ask: "If I need to scale this to 10x the users, where will it break first?"
"Documentation for Humans": Use AI to help you write a README that speaks to both developers (technical) and managers (value-driven).

AI handles the "how," which leaves you free to master the "why."

Final Thought: Setting the Stage

In my next posts, I will finally open my GitHub for the projects I’ve been talking about.

But I won't just dump code there. I’ll be applying everything we’ve discussed: Simplicity, Testing, and Business Value. I want to show you that a "Senior Portfolio" isn't about how many stars you have, but about how clearly you demonstrate your ability to solve real problems.

Are you ready to stop just "coding" and start "engineering"? What’s the biggest non-technical challenge you face at work? Let’s discuss below!

Mistakes I Made as a Developer (And What They Taught Me)

Renato Silva — Sun, 15 Mar 2026 09:17:50 +0000

If you stay long enough in software development, you will make mistakes.

Not small ones.

Real ones.

Bugs in production.

Bad architectural decisions.

Features that had to be rewritten from scratch.

When I started my career, I thought good developers avoided mistakes.

Now I understand something different:

Good developers learn faster from them.

Here are some mistakes I made during my journey — and what they taught me.

1. Trying to Know Everything

Early in my career I believed I needed to understand everything.

Every framework.

Every new tool.

Every programming language trend.

The result?

Constant context switching.

I was learning many things, but mastering none.

What I eventually realized is that depth matters more than breadth.

It's better to deeply understand a few tools than to superficially know many.

2. Writing “Perfect” Code Too Early

Another mistake I made was trying to write perfect code from the beginning.

Spending too much time:

refactoring early
overthinking architecture
worrying about edge cases that never happened

But software development is iterative.

Often the best approach is:

Write something simple → make it work → improve it later.

Perfection too early slows progress.

3. Avoiding Asking Questions

For a long time I hesitated to ask questions.

I thought it might make me look inexperienced.

So instead I would spend hours stuck on problems that could have been clarified in minutes.

Eventually I realized something important:

Good teams respect thoughtful questions.

Asking for help is not weakness.

It's efficiency.

4. Underestimating the Importance of Communication

At first I believed programming was mostly about writing good code.

But over time I learned that communication is just as important.

Explaining decisions.

Discussing trade-offs.

Aligning with teammates.

Great developers are not only good coders.

They are also good communicators.

5. Ignoring the Bigger Picture

When you're early in your career, it's easy to focus only on the code in front of you.

But software exists inside larger systems.

Understanding things like:

system architecture
user impact
scalability
product goals

changes the way you approach problems.

Coding becomes more intentional.

6. Waiting Too Long to Build Personal Projects

For a long time, most of my coding happened only at work.

But personal projects teach things that professional environments sometimes don't.

They give you:

full ownership
freedom to experiment
the chance to try new ideas

Even small projects can expand your thinking as a developer.

7. Not Realizing How Long the Journey Is

In the beginning, I thought becoming a strong developer would happen quickly.

But this field is a long-term journey.

There is always more to learn.

New tools.

New patterns.

New ways to solve problems.

And that's actually one of the best parts of it.

Final Thought

Mistakes are not the opposite of progress.

They are part of it.

Every developer has a list of things they would do differently today.

The important thing is to keep learning from those experiences and keep moving forward.

Because in software development, improvement is continuous.

And that's what makes the journey interesting.

Why I’m Choosing Simplicity for My Next GitHub Projects

Renato Silva — Sun, 15 Mar 2026 09:10:12 +0000

I’m starting a series of practical projects to demonstrate that clean, simple architecture is the best way to build software. Here is the plan.

In my last post, I talked about why Simple Architecture is a superpower.

But talk is cheap. Code is what matters.

To prove that you don't need overengineered systems to build high-quality software, I’m starting a series of small, real-world projects that I’ll be sharing on GitHub.

My goal is twofold:

To show that a clean, well-tested "boring" stack is often better than a complex trendy one.
To help other developers see how to structure projects that are easy to maintain and scale.

Here is the "Mental Framework" I’m using to choose my tools and why this matters for your career too.

1. The "Boring Technology" Rule

For these projects, I’m avoiding the "flavor of the week" frameworks.

I’m choosing technologies that are stable, have great documentation, and a strong community. Whether it's Node.js, Python, or Go, the focus isn't on the language itself, but on how I solve problems with it.

Why? Because companies don't want a developer who experiments with their production code. They want someone who delivers reliable solutions.

2. Focus on "Core Logic" first

In the upcoming projects, you will notice that the business logic is separated from the framework.

If I’m building a CLI Tool (my first project!), the logic that calculates a task shouldn't care if it's running in a terminal or a web server. This is the heart of simple architecture.

3. README as a First-Class Citizen

A project without a good README is like a book without a cover.

For every repo I share, I’m focusing on:

The "Why": What problem does this solve?
The "How": Clear installation and usage instructions.
The "Tests": Showing that the code works as expected.

How AI is Helping Me Prototype Faster

I'm using AI to speed up the "setup" phase of these projects. Here’s how:

"Boilerplate Generation": Instead of spending an hour setting up a folder structure, I ask AI to generate a clean, modular structure based on my architectural rules.
"Documentation Drafts": I feed my code to the AI and ask it to write the first draft of the README. I then refine it to ensure it has my "voice" and technical accuracy.

AI allows me to focus on the decisions, while it handles the repetition.

What’s Coming Next?

The first project will be a CLI Tool designed to solve a common developer pain point. It will be small, fast, and 100% open-source.

I want to show you that a professional repository isn't about the number of files, but the quality of the decisions inside them.

What do you value most when you look at someone's GitHub? The complexity of the code or the clarity of the documentation? Let's talk below!