This took me almost 2 months of hiatus reading books, writing post morterms and learning from my past mistakes. Let me share with you what's important in tech startups:

Architecture matters

In previous projects, I ended up with technical debt that was impossible to paid without a major rewrite and I had either premature or wrong abstractions. In any serious software project that you have to maintain over time, you need to consider using a serious architecture to keep consistency.

With software architecture, I'm not meaning to the folder structure where you separate your code by services, controllers and views. You can separate your code by folders and it can still create cognitive overhead because of god objects and nonexistent abstractions.

Cognitive overhead is avoided isolating responsibilities. Use cases do one functionality well and you use ports and adapters to make your code like lego blocks.

However, architecture is a medium, not the end. You don't need to follow all clean code standards perfectly, just ensure your team has standards, quality assurance (QA) and you can adapt to the change of requirements.

Kill scope creep

I learned how to spot scope creep after falling for it several times. Scope creep refers to any features you believe help the product before you've validated your idea well, even if you don't have proof.

Common examples are:

• Search inputs in feeds with less than 100 total users (but you can find everything in a single page...)

• Filters and multiple categories in a social media feed MVP (are the people even posting there?)

• Combining multiple app functionalities in a single one (is this a social media app, a habits tracker or what?)

• Features that consider paranoid edge cases (let's add multiple timezones because of... let's send the user a message in 5 different ways...)

I've been telling this to other startup founders and entrepeneurs. First, validate your core feature and get users. Later, if users ask for these features, we can add them.

Something else happens when you don't cut off scope creep:

Your product gets more complex to use and your users stop using the app.

This note itself has its worth in gold. Keep your products and ideas simple, add new features and functionalities only when other people ask for it.

Question everything

Most people have labeled me as a rebel or paranoid. In business this is a blessing, because when you don't question an idea, you build without a plan and blindly. You're being reactive, not proactive.

Always make sure to ask these questions to your team:

• When is the actual deadline for this project? (always be asking this, it might sound relevant but PMs and non-technical people change their minds quite often)

• Why is this needed and what do you expect from this project or functionality?

• How is this feature helping users and why is it important?

• How are we different from the competition and why is people going to use our products?

• Do we need this feature or are we building it just in case?

Also question your architecture choices often:

• Do I need to add Websockets here when I can use server sent events?

• Is Redis needed here or am I just thinking about a fictional scenario?

• Am I normalizing my schemas for the sake of it or is this helping the business?

• Why am I even doing optimistic updates when I can just make a new API call for MVP?

Solve your own problems first

I used to hate sending invoices because I was doing the whole process by hand.

I automated it using n8n, Google Docs, Gmail API and JavaScript in a weekend, now it saves me 2 hours monthly.

To be honest I also dislike sending weekly engineering reports by hand because it's all on the Git history but someone has to translate it to stakeholders.

So I built another automation. It gets the git history of a repository and turns it into business results. I tweak it and I have a meeting agenda.

These are for my business and they're humble integrations that solved actual problems I had. my message here is simple:

Fix problems for yourself before solving them for others

How can you guide and support other people if you're not able to support yourself first? You need to be willing to learn from your mistakes and find ways to improve yourself.

Maybe your next business idea is an app you build for yourself first.

Think about it :)

Choose your path

I tried to get into FAANG and I was chasing it, but for what really? Money and reputation? That's not what I want right now.

I promised myself I was not going to compete with other engineers to land a fancy job.

I've preferred to work with non-technical founders, dive deeper into backend engineering, automation and the business side of things. So far, it's worked well and we've shipped great software.

To some people I'm a mentor, for others a founding engineer, and some people don't even know what I do.

This is what I do. I help founders build startups, digital products and I educate others about software engineering and architecture.

It's okay if you want to land a job in a startup.

It's okay if you want to get into FAANG.

It's okay if you want Series C funding.

It's okay if you want to build an app and share it with other people.

As long as you're aware of your strengths, weaknesses, personality traits and understand there won't be an easy path, you'll make progress in your journey.

General Advice

• Give time buffers. If a project is estimated to take you 3 months, explicitly mention it'll be 5 months. You don't know what might change or how life develops.

• If you're consulting, greenfield projects are charged by milestones, not by the hour. It's more beneficial for you and your employer.

• Surround yourself with great people who are willing to improve daily.

• Don't take failure personally, study why things failed, learn to never do so again and move on.

• Don't fix the symptom of a problem, fix the root of it. This applies to everything in life.

• Learn new things outside work, read and experiment with new technologies. Your main position or gig can burn you out if you don't introduce variation in your life.

• Always be willing to have tough talks with your people. Be clear and honest about your perspective and long term thinking.

• Make your codebase and configuration as flexible as possible in startups, your mental health will thank you.

• Your goal as an entrepreneur is to help more people.

• It's better to spend 1 week planning than 1 year building mindlessly.

• Remember, entrepeneurship is the medium, not the end.

Thanks for reading! I hope you've learned something new here. You can also learn more about my projects in my website: https://www.itsfranciscoluna.com/

This blog is a collection of lessons I wish I had earlier. It’s not about being perfect but about building systems that are clean, scalable, and maintainable in real-world conditions. Whether you’re solo or in a small team, these practices will help you ship faster, debug less, and build with confidence. Let’s get started.

📘 Leverage OpenAPI and Documentation Standards

OpenAPI has become the standard specification for modern APIs. It allows you to document your endpoints, DTOs, responses, and error codes in a structured, scalable way. Once defined, your specification can be visualized using open-source tools like SwaggerUI or Scalar, giving your team and clients a clear view of your API’s surface.

Implementation might be different across codebases. Some teams still write specs manually, which I don’t recommend. Others use tools like zod-to-openapi or framework-native solutions to generate specs directly from validation schemas and DTOs. Personally I prefer a programmatic approach, keeping the spec in sync with the codebase ensures accuracy and reduces friction.

💬 What About the Client? Common Pitfalls & Solutions

So far, we’ve focused on backend documentation. You might visit your generated docs at:

http://localhost:3000/docs

…and see a beautifully rendered list of endpoints. But if you’re a Full Stack Engineer, a solo dev, or part of a frontend team, manually recreating every type and contract on the client side is a recipe for inconsistency. Even with AI assistance, it doesn’t scale; especially when schemas evolve.

That’s why I recommend using libraries like OpenAPI TypeScript. These tools generate type-safe clients directly from your OpenAPI spec, ensuring your frontend stays aligned with your backend without redundant effort. In our mono-repo setup, this approach has been a game-changer.

🧠 Separate Business Logic

This isn’t a blog about hexagonal architecture, clean architecture, or MVC and I’m not here to tell you which one to follow. What matters is separation. You need to understand how to structure your application so that logic isn’t tangled in a single file or scattered across untraceable layers.

✨ What Separation Actually Means

• Repositories → Handle data access and persistence

• Controllers → Receive requests, delegate to services

• Services → Contain business logic, orchestrate flows

• Infrastructure Layers → External systems (e.g., DB, cache, queues)

• DTOs → Define shape and contract of data

• Entities / Tables → Define how the core business model or entity will be created

• Routes → Map endpoints to controllers

• Validations → Ensure data integrity before logic runs

• Types → Enforce clarity across the stack

• Dependency Injection / Containers → Manage lifecycle and initialization

❌ What to avoid

I’ve seen this countless of times. It’s okay for prototypes and quick iterations but please, don’t come up with this in a project that will scale:

app.post('/create-user', async (req, res) => {
  const { name, email } = req.body;
  const user = await db.insert({ name, email });
  res.json(user);
});

✅ What to aim for

// route.ts
router.post('/create-user', userController.createUser);

// controller.ts
export const createUser = async (req, res) => {
  const user = await userService.create(req.body);
  res.json(user);
};

// service.ts
export const create = async (data) => {
  validateUser(data);
  return userRepository.insert(data);
};

📁 Folder Structure and Architecture

You don’t need to follow a single architectural dogma. Whether it’s Clean Architecture, DDD, Screaming Architecture, or a hybrid, what matters is that your structure scales and your team can read it without friction.

Personally, I lean toward a layered pattern that balances clarity and modularity:

• API Layer → Routes, Controllers, Schemas, Services, Repositories, Validations, Entities

• Global Layer → Shared infrastructure (AWS SDKs, Sentry, Stripe, etc.), types, utilities, and specs

📋 Document Everything

In the codebase I’m currently working on, there are several non-obvious configurations that, if undocumented, would lead to significant friction and confusion. For example, due to limitations with ESM modules and specific ORM behaviors, we must compile the backend application before executing database migrations. Additionally, our seeding process involves junction tables that are essential for scalability, and each project within the monorepo includes its own .env.example file to manage environment variables.

Without clear documentation of:

• The ESM module constraints impacting migration execution.

• The seeding logic required to initialize the application correctly.

• The environment variables distributed across modules.

• The onboarding experience would be chaotic, and maintaining the system would become unnecessarily burdensome.

✨ Best Practices

• If you uncover a cryptic configuration, document it.

• If you discover a way to improve CI/CD, share it and document it.

• If you encounter a bug that only you understand, fix it and document it immediately.

🎹 DRY and Design Patterns

When I first joined this backend codebase, I made a classic mistake. I created a separate repository for every single entity, even when their logic was nearly identical…

For example, we had tables for daily, weekly, and monthly tasks, and I wrote three distinct repositories with almost the same CRUD operations:

Technically, this worked. But it introduced a long-term problem: Every schema change, every refactor, every new feature had to be triplicated. It was fragile, redundant, and emotionally exhausting.

// dailyTask.repository.ts
export const createDailyTask = (data) => db.dailyTask.create(data);

// weeklyTask.repository.ts
export const createWeeklyTask = (data) => db.weeklyTask.create(data);

// monthlyTask.repository.ts
export const createMonthlyTask = (data) => db.monthlyTask.create(data);

📚 Refactoring with DRY Principles

To resolve this, I consolidated the logic into a generic task repository using abstraction and shared patterns:

// task.repository.ts
export const createTask = (type: 'daily' | 'weekly' | 'monthly', data) => {
  return db[`${type}Task`].create(data);
};

You can apply guard clauses, strategy patterns, or other abstractions depending on your context. The key is to avoid duplicating logic that behaves the same across entities.

✅ Benefits of This Approach

• Reduces duplication

• Centralizes logic

• Simplifies future changes

• Improves testability and readability

• Honors the DRY principle

🧠 KISS – Don’t Overcomplicate Things

No. You don’t need an AbstractClassAppInitializationFactory when you’re not even in the market yet.

The purpose of an MVP (Minimum Viable Product) or MLP (Minimum Lovable Product) is to deliver something of value to your initial users. KISS is not an excuse to ignore best practices. You SHOULD still use reusable patterns, structure your code, apply Dependency Injection, and follow clean conventions. But complexity should be introduced only when it’s necessary.

You can scale with Redis. You can scale with Nest.js. You can scale with a monolith that’s well-structured.

But if you’re building abstract design patterns that delay delivery just to sound smart you’re not building a product. You’re digging your own grave. Especially if your team is small or if you’re solo.

❌ Bad - Too Much Initial Complexity

interface PostDeletionStrategy {
  execute(postId: string, userId: string): Promise<void>;
}

class DeletePostHandler implements PostDeletionStrategy {
  constructor(
    private repo: {
      getById: (id: string) => Promise<{ userId: string } | null>;
      deleteById: (id: string) => Promise<void>;
    },
    private auth: {
      isAuthorized: (userId: string, ownerId: string) => boolean;
    }
  ) {}

  async execute(postId: string, userId: string): Promise<void> {
    const post = await this.repo.getById(postId);
    if (!post) throw new Error('PostNotFound');
    if (!this.auth.isAuthorized(userId, post.userId)) throw new Error('Forbidden');
    await this.repo.deleteById(postId);
  }
}

class PostService {
  constructor(private deletion: PostDeletionStrategy) {}

  async delete(postId: string, userId: string) {
    await this.deletion.execute(postId, userId);
  }
}

const service = new PostService(new DeletePostHandler(repo, auth));
await service.delete('post123', 'user456');

This works but there’s too much complex logic for a single operations. You’ve introduced interfaces, base handlers, and strategy patterns before even validating the product…

✅ The Fix: Just Go to Market with Good Practices

type Dependencies = {
  repo: {
    getById: (id: string) => Promise<Post | null>;
    deleteById: (id: string) => Promise<void>;
  };
};

export function PostService({ repo }: Dependencies) {
  return {
    deleteById: async (id: string, userId: string) => {
      const post = await repo.getById(id);
      if (!post) throw new Error('Not found');
      if (post.userId !== userId) throw new Error('Forbidden');
      await repo.deleteById(id);
    },
  };
}

This version is clean, testable, and scalable. It honors separation of concerns without being complex. It gets you to market faster and will allow you to work on other features as well.

🐳 Docker - Real Life Development Environments

A lot of people ask me why I love Docker. One year ago, a client asked me to run a project for them. They cloned the GitHub repo, followed the installation instructions, and then… CHAOS.

They had to manually set up PostgreSQL, Redis, Node.js, PNPM, Next.js, run database migrations, configure Stripe and other external integrations... It was one of the most awkward dev experiences I’ve ever had. Months later, I learned Docker and Docker Compose, and it changed everything. I now save 8+ hours a week by avoiding manual setups, Linux environment configs, and repetitive integration commands. Everything’s dockerized and automated in my dev environment.

Do yourself a favor: leverage automation scripts in your IDE, learn Docker and containerization, and document every environment variable in a .env.example file.

You don’t want to go through what I did. TRUST ME.

🧾 Clear API Responses

Clear API responses matter. Don’t manually return JSON objects in every controller. You’ll forget field names, break consistency, and end up with endpoints that return "info" instead of "data" because you got creative.

Instead, build a simple response adapter. It can be just a dictionary of methods that wrap your response logic. This way, every success, error, or edge case goes through the same structure. You define it once and call it everywhere. It’s not fancy, it’s just maintainable. Your future self will thank you when debugging a 409 Conflict at scale doesn’t feel like a Dark Souls bossfight. Keep it clean. Keep it predictable.

❌ Bad Practice - Manually Creating the Response

return res.status(200).json({
success: true,
data: someData
statusCode: 200
})

✅ Good Practice - Using an Adapter

An adapter is a artifact which you can use to turn data from external systems into your own. Ideal for API responses and data transformation such as the example down below!

export const ApiResponse = {
  success: <T>(res: Response, data?: T, message = 'Success') =>
    res.status(200).json({ statusCode: 200, message, data }),

  created: <T>(res: Response, data?: T, message = 'Created') =>
    res.status(201).json({ statusCode: 201, message, data }),

  error: (res: Response, message = 'Error', statusCode = 500, error?: any) =>
    res.status(statusCode).json({ statusCode, message, error }),

  notFound: (res: Response, message = 'Not Found') =>
    res.status(404).json({ statusCode: 404, message }),

  badRequest: (res: Response, message = 'Bad Request', error?: any) =>
    res.status(400).json({ statusCode: 400, message, error }),
};

Which you can use like this in a controller now!

return ApiResponse.success(res, serviceResponse, 'Successfully fetched the user.')

🔥 Leverage Cache

Why does cache even matter? Let’s talk about how we use junction tables in an application. When setting up the app in a new environment, we need to seed the database with categories, filters, and metadata. It’s not fun, but it’s the most scalable way to keep things normalized. We tried using JSON blobs and string[] arrays, but they didn’t scale well. So we built a proper repository and added cache.

We constantly query for things like interests and categories. These don’t change often, maybe once every few months. But we were still hitting the database every time. That works with 100 users. Not with 10,000. It’s a waste of resources at scale.

const TOPICS_CACHE_KEY = 'topics:all';
const CACHE_TTL = 60 * 60 * 24; // 24 hours

export const UserTopicsRepository = (db: any, redis: any) => {
  const getTopics = async (): Promise<{ id: string; slug: string }[]> => {
    const cached = await redis.get(TOPICS_CACHE_KEY);
    if (cached) return JSON.parse(cached);

    const topics = await db.select().from('Topics');
    await redis.set(TOPICS_CACHE_KEY, JSON.stringify(topics), { EX: CACHE_TTL });
    return topics;
  };

  const syncUserTopics = async (userId: string, topicSlugs: string[]) => {
    await db.delete('UserTopics').where({ userId });

    if (topicSlugs.length === 0) return;

    const allTopics = await getTopics();
    const slugToId = new Map(allTopics.map(t => [t.slug, t.id]));

    const topicsToInsert = topicSlugs.map(slug => {
      const id = slugToId.get(slug);
      if (!id) throw new Error(`Topic '${slug}' not found`);
      return { userId, topicId: id };
    });

    await db.insert('UserTopics').values(topicsToInsert);
  };

  return { syncUserTopics };
};

That’s why we use Redis. Another would be, when anonymous users view public posts, you can’t afford to fetch the same content over and over. These users don’t carry state, but they bring volume. So we cache what’s static: metadata, categories and tags. We only fetch dynamic states like isLiked or isFollowing when needed.

Follow a simple rule: cache what doesn’t change often. This protects your database, improves response times, and keeps your system scalable.

🎹 Final Thoughts

I used to hate backend development 1 year and a half ago. But it was because I didn’t know those principles and I was constantly repeating myself, creating fancy implementations that didn’t scale and duplicating my code over and over again.

The good thing is that you don’t need to suffer through fragile environments, weird abstractions, or inconsistent APIs. You just need to build with intention. Whether it’s Docker, clean response adapters, DRY repositories, or Redis caching; every decision should move you closer to clarity, not complexity.

If you’re solo or in a small team, your codebase is your second brain. Don’t clutter it with patterns you don’t need (or understand) yet. Don’t delay delivery to sound smart. Build something that works, scales, and makes sense to the next person who reads it; even if that person is you, three months from now.

Honestly speaking, this is the guide I’d shared with my past self. I had to learn things the hard way. But you don’t have to. Remember. Never stop learning, don't be afraid of breaking things and always keep experimenting.

I've been working on database design at a startup, and this time, it feels like the system is no longer against me. It's all about best practices, scalability, and clear conventions. But this didn't happen suddenly; it took countless mistakes, hours, and pain.

I've gone through the process of learning the best practices on my own and ensuring my schemas can actually scale, so you don't have to go through the same painful process. Here are the 10 database design lessons I learned the hard way.

1. Avoid overusing enums

An enum (enumeration) is a data type that lets you define a list of possible string values a column can hold. The database then enforces that the data inserted into that column must be one of those values. They are great for small, unchanging sets of values but they're a pain to update because it requires a schema migration.

Lookup tables are separate tables that contain a list of values, and your main table references them using a foreign key. This makes the values easy to manage, add, or remove without changing the main table's schema.

Simple Enum in PostgreSQL:

CREATE TYPE user_status_enum AS ENUM ('active', 'inactive', 'suspended');

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    status user_status_enum NOT NULL
);

Scalable Lookup Table Schema:

CREATE TABLE post_categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    category_id INTEGER REFERENCES post_categories(id)
);

Backend Dictionaries

These are data structures in your application code that hold a list of valid values for a specific field.

// This data structure is dynamically populated from the database
interface CategoryDictionary {
 [categoryName: string]: number;
}

const CATEGORIES: CategoryDictionary = {
 'Tech': 1,
 'Music': 2,
 'Travel': 3
};

// Example usage
const categoryId = CATEGORIES['Tech']; // Returns 1
const isValidCategory = !!CATEGORIES[categoryName]; // Checks if a category exists

While they can be a useful tool for validation, simply using a static array of strings in the database isn't a robust solution on its own. It directly violates the principles of database normalization by creating a redundancy between your application and your database schema.

If the list of valid values changes, you have to update your code and potentially your database, leading to a disconnect between the two sources of truth. A more normalized approach is to use these dictionaries alongside a lookup table. The dictionary in your backend can be populated from the lookup table in your database on application startup. This way, the database remains the single source of truth for the list of values, and your application always has the most up-to-date data for validation.

2. Design for the Business, Not for Convenience

This principle is about creating a database schema that accurately models the real-world business concepts, rather than what's easiest for your code. A DATE data type, for instance, represents a full calendar date. While a developer might find it convenient to store a birthday as three separate integers for year, month, and day, the business understands a birthday as a single date. Using the correct data type ensures your database reflects the truth of the business.

Bad Design:

CREATE TABLE user_birthdays (
    user_id SERIAL PRIMARY KEY,
    birth_month INTEGER,
    birth_day INTEGER,
    birth_year INTEGER
);

Good Design:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    birthday DATE
);

3. Consistency Matters

Consistency means using the same naming conventions, data types, and structural patterns throughout your entire database. For example, if you choose snake_case (e.g., user_id), you should use it everywhere. Inconsistent naming like user_id in one table and userId in another leads to confusion and bugs.

Inconsistent Naming (Bad):

CREATE TABLE users (
    user_id SERIAL PRIMARY KEY
);

CREATE TABLE user_posts (
    post_id SERIAL PRIMARY KEY,
    userId INTEGER
);

Consistent Naming (Good):

CREATE TABLE users (
    id SERIAL PRIMARY KEY
);

CREATE TABLE user_posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id)
);

4. Everything Should Serve a Purpose

Every table, column, and index in your database should exist for a specific, current business requirement. Over-engineering is the act of building features or adding complexity that isn't currently needed, often with the thought of "just in case." This adds unnecessary complexity and can harm performance. The goal is to keep the database as simple as possible while meeting all requirements.

Over-engineered (Bad):

CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    shipping_notes TEXT,
    supplier_id INTEGER,
    is_on_sale BOOLEAN,
    sale_price DECIMAL(10, 2),
);

If your business only has one supplier and products are never on sale, these columns are just clutter. Don't try to cover all possible future cases when a feature hasn't even been requested yet.

5. Don't Let the Database Handle Authentication

Your database is a data store, not a security server. Don't rely on features like PostgreSQL's Row-Level Security (RLS) for core authentication, please. It sounds easy to do, but you’re introducing provider-lock in. What if you change the database you’re working with in the future? That’s why all authentication and password hashing should be handled in your application layer.

Example RLS Policy (to show what to avoid):

-- Now your app's security is coupled to the DB...
CREATE POLICY user_access ON user_posts
    FOR SELECT
    USING (user_id = current_setting('app.user_id')::integer);

6. The Database Shouldn't Handle Business Logic Validations

Validation is the process of ensuring data is correct and meaningful. The database should only perform basic validations like ensuring a field is not null or that a value is unique. Complex business logic, like checking if a number is between 1 and 12 for a month, should be handled by your application code. This separation of concerns keeps your database clean and your application flexible.

Application-level validation (Better):

// In your backend code
if (month < 1 || month > 12) {
  // Error handling
}

7. Separate Staging and Production Databases

Production is the public-facing environment. Staging is a pre-production environment used to test new features. You should never work directly on your production database. Mistakes are inevitable. Having separate databases creates a safety net, so you don't accidentally delete real customer data. I recommend you using a product like Hashicorp Vault to properly save the credentials and URLs to work with these environments.

8. Never Take Scalability for Granted

Scalability is the ability of a system to handle a growing amount of work. It’s a mindset you must adopt from the beginning. A key part of this is understanding the impact of your design choices. An index is a data structure that improves the speed of data retrieval operations on a database table. Forgetting to add them to foreign keys is a common mistake that can lead to major performance issues as your data grows.

Adding an Index

CREATE TABLE user_posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id)
);

CREATE INDEX idx_user_posts_user_id ON user_posts (user_id);

Think About the Long Term

Always build your tables with the expectation that there will be changes and new features.

Spoiler: There will always be changes.

This means you should design for the long term. A critical part of this is adding a new column. To avoid database conflicts during a migration, a new column must be nullable or have a default value. This prevents live applications from failing when they try to insert new data. While a nullable column is a common and necessary workaround, using a default value is often a better practice from a data integrity standpoint, as it avoids nulls and maintains a cleaner dataset.

Document Your Schemas

In a startup, your data structures will evolve quickly. When using flexible data types like JSON or JSONB to store semi-structured data, it's easy to lose track of the schema. That's why you should document your JSON/JSONB schemas and structures through a formal specification like OpenAPI. This ensures that your entire team and any future consumers of your API understand the data format, preventing errors and ensuring consistency.

9. Use the Right Data Structures

Choosing the correct data type (e.g., BOOLEAN, DATE, JSONB) for a column is important for performance and clarity. JSONB is a PostgreSQL data type that stores JSON data in a binary format which allows you to index and query it efficiently. It’s perfect for semi-structured data where the schema might be flexible.

Example with JSONB:

CREATE TABLE social_media_posts (
    id UUID PRIMARY KEY,
    metadata JSONB
);

INSERT INTO social_media_posts (id, metadata)
VALUES (
    'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
    '{"tags": ["newmusic"], "likes": 150}'
);

10. Always Choose UUIDs Over auto_increment IDs

An auto_increment ID is a simple integer that automatically increases with each new row. A UUID (Universally Unique Identifier) is a 128-bit number that is globally unique. UUIDs are essential for distributed systems because they can be generated anywhere, on a client, in a microservice; without a central authority to ensure uniqueness. This prevents ID conflicts and makes your system much more scalable and secure.

Why UUIDs are better:

• No Conflicts in Distributed Systems: With auto_increment, two different services inserting data at the same time might generate the same ID. UUIDs solve this problem.

• Security & Data Leaks: Predictable, sequential IDs like 1, 2, 3... are a major security risk. A malicious user can simply try incrementing IDs in an API endpoint (e.g., /api/users/1, then /api/users/2) to scrape or access other users' data. With UUIDs, the IDs are random and impossible to guess, protecting against these types of attacks.

Example in PostgreSQL:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid()
    email VARCHAR(100) UNIQUE NOT NULL
);

-- The UUID is generated automatically
INSERT INTO users (email) VALUES ('janedoe@example.com');

Conclusion

Database design is a brutal teacher in software engineering. The most painful lessons aren't in a tutorial when you're developing; they're in production, where a small mistake can become a colossal monster. Don't be discouraged by your blunders or failures as they're the very thing that forges your mastery.

Think of it like Dark Souls. You don’t get good by avoiding the bosses; you get good by facing them, learning their patterns, and finally beating them. The ten lessons in this post are your strategies. Now you're ready to face your own production monsters. I know I'll be facing more challenges, and I'm willing to keep sharing with you everything I learn on this journey.

See you in the next entry. Don’t let the abyss consume you.

By the day I'm writing this, in August 17th we've gotten:

• 41 people across 4 continents using Veelo

• 1 rating

That’s 10 people per continent! It's all been organic traffic, networking and reaching out to existing communities. I'm really proud of it so far.

The process sounds fun and it seems like I'm winning. Maybe I’m, but I've only ensured to follow a few key principles after several failed products and ideas of mine, hence why I believe things are actually working out this time.

It's not luck. It's engineering, psychology and sales. Similar to Dark Souls, I had to "die" a lot to get good at this game.

Let me share my lessons with you and what's working this time.

You don't need to reinvent the wheel

Let's start by clarifying something. Veelo is not a tool to highlight notes in a website primarily. It's used as a smaller version of Note which you can carry across different websites. Each website you visit can have their own notes, and you can also pin notes, making them show up in almost all websites you visit.

I'd also tested Note Anywhere, another good extension to work with sticky notes. But I found a few problems with the UX/UI. You cannot use markdown, you cannot highlight text, you cannot name notes and the UI feels intrusive sometimes.

It served as an inspiration to build Veelo, which combines the UX/UI of Notion with the capabilities of Note Anywhere, and beyond!

The lesson? Remix and take inspiration from others. 🚀

Build with and for actual users

One of the reasons why Veelo has been well received by the first users is because of how easy it's to use. But it wasn't always like this! While working with students in the development stage, I noticed important problems and limitations:

• Everything was markdown based (A language used primarily by technical users)

• No menu or guidance for the average user

• No highlighters

• Notes didn't even have titles

I regret making Veelo this technical at the beginning to be honest. Beta testers literally saved the product, I couldn’t be more grateful for that.

While it was brilliant, I was clearly missing basic functionalities to make it useful.

That’s when I learned the following: never build alone. Always ask for feedback and recommendations, even if it comes from friends. Otherwise you're just building for a void. And you actually want people to use your products.

Don't limit your target audience

Veelo initially was built only for developers, as I was trying to solve my own problem of multitasking between technical documentation from work, and my browser. This didn’t work out because:

• My problem was almost non-existent given all tools available for developers

• Students struggled the most with similar problems

• There were better alternatives for developers. Yet the average user or student didn’t have much intuitive tools

Hence why I ended up pivoting the idea from a developers tool to one for students and non-technical users. Devs can also benefit from it, as well!

Launch is just the beginning

Sure, you launched your product and gathered your first users. But if you want to keep helping people with it and accomplish your goals, you actually need to have a long term plan.

It could be:

1. Reaching 762 users by December and 52 daily active users

2. Featuring in Dev.to or HackerNews

3. Monetizing one feature by January 2026

But Fran, why are you this strict? My friend, if you're really serious about your growth:

• It forces you to find a way to accomplish those goals

• It helps you think about the long term. Launching product is fun. But the process of networking, scaling and following long term strategies will required you to be disciplined and have a plan.

You might get far without a plan. But even a bad plan is better than no plan at all.

Next Plans

Next time, I’ll reveal the hardest engineering decisions I had to make (and how they almost killed the product) in a study case. I’ll keep focused on learning from user feedback, improving my skills at work and keep sharing my knowledge.

Thank you so much for reading! You can follow my journey on LinkedIn as well. Let’s keep fighting the abyss together.

The sword Of Damocles

July 2025. I had just finished university. Stable job, hobbies, freedom, a social life. It was all “good”. Yet I felt like a bird in a cage; exhausted, uninspired and trapped in routines that weren’t even mine.

I started to lose my passion for building outside of work. Tasks and tickets mixed together. I was in an emotional limbo. My family asked if I was okay. I wasn’t. I was documenting every lesson learned at work: From public speaking, leading complex refactors to handling life changes; all at once.

Then I came across the book Buy Back Your Time by Dan Martell. One quote hit me like a lightning bolt:

“If your business depends on you, you don’t own a business—you have a job. And it’s the worst job in the world because you’re working for a lunatic!”

All of a sudden it clicked. I was undervalued. My skills, my creativity, my ownership; they weren’t mine. They were borrowed. And when the startup stalled, so did I.

The Startup Illusion in 2025

The first 5 months (Heaven):

• Built our payment system from scratch

• Scaled real-time features to 1K+ concurrent users

• Designed our Redis caching layer

This was pure flow state and why I fell in love with coding.

Then reality hit:

• Renaming variables just to “do something”

• Sitting through two hour compliance meetings

• “Refactoring” perfectly working code

What kind of engineering was this? My passion was just dying.

The Wake-Up Call

That week, I realized:

• Skills stagnating

• Creativity dying

• Passion fading

• Worst of all, I’d stopped building for myself

If I only built at work, my growth was limited by the company’s pace, bureaucracy, and whatever stage the startup was in. I had to reclaim my ownership.

The Escape Plan

To start claiming back my freedom I launched Veelo, a browser extension that:
✓ Captures ideas instantly
✓ Organizes technical notes
✓ Preserves brilliant “shower thoughts”

It started as a prototype in May 2025 when I opened a white IDE and I had a crazy idea. It gathered 21 users the first day, which doesn’t sound like a lot. But it meant my work was helping other people somehow.

The best part? No stakeholders. No pointless meetings. Just me solving real problems for myself. Coding was fun again. And I remembered why I started building in the first place: curiosity, ownership and mastery.

That’s when I felt alive again after months

Next Plans

Veelo was just the beginning. I want to keep building meaningful projects, solve problems I care about, and push my skills beyond the 9 to 5.

I’ll share the wins, the failures and the messy middle. Because potential isn’t something your employer gives you, it’s something you own.

Work will stall and bureaucracy will slow you down. But the things you build for yourself? They’re yours. They grow you. They teach you, and set you free.

Thanks for reading. I only want you to keep this simple reminder in mind from now on:

Don’t ever go hollow building someone else’s empire only.