notesverb-yt: The Honest Microservice Blueprint: Inside NotesVerb

The Microservice Lie

Most microservice tutorials lie to you. They spin up multiple Node.js services but quietly point them all to a single shared PostgreSQL database. This completely defeats the purpose of bounded contexts.

NotesVerb takes the hard path. It provisions distinct Prisma schemas for the Auth, User, Notes, and Tags services. It trades local convenience for genuine architectural scalability. By refusing to share database tables, it forces developers to solve the actual problems of distributed systems.

The Gateway as the Brain

In a truly distributed system, individual services should not waste cycles verifying authentication tokens. NotesVerb solves this at the edge using its API Gateway layer.

Once the gateway verifies a JWT, it performs header enrichment by attaching the x-user-id to the request before proxying it downstream. This allows the internal Express services to remain completely isolated from the authentication database while still knowing exactly who is making the request.

The Distributed Join Problem

Because Notes and Tags live in entirely different databases, the Notes Service cannot execute a simple SQL JOIN to validate a tag. If a user tries to label a note with a specific tag ID, the system must cross a network boundary to verify that the tag actually exists.

This is where the TagsServiceClient comes in. It is an internal HTTP client that encapsulates the network logic required to bridge these bounded contexts. Instead of a database query, it performs an internal POST request to the Tags service.

export class TagsServiceClient {
  private baseUrl: string;

  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  async validateTags(tagIds: string[], userId: string): Promise<boolean> {
    try {
      const response = await axios.post(`${this.baseUrl}/validate`, { tagIds }, {
        headers: { 'x-user-id': userId }
      });
      return response.data.valid;
    } catch (error) {
      throw new Error('Failed to validate tags across service boundary');
    }
  }
}

DRY in a Distributed World

Microservices often lead to massive code duplication. NotesVerb combats this by utilizing a dedicated shared directory strategy. By centralizing TypeScript types, error handling middleware, and health checks, the project ensures consistency.

This centralized logic dictates that every isolated service still speaks the exact same JSON dialect to the frontend. It is a vital layer of standardization in an otherwise decentralized architecture.

Escaping the SaaS Wrapper

The market is flooded with bloated, VC-funded YouTube summary SaaS products. They lock your personal knowledge graph behind credit-based AI wrappers and proprietary vector searches.

NotesVerb offers an alternative. It provides a vendor-neutral, self-hosted chassis for building personalized knowledge graphs. It is an infrastructure blueprint rather than a consumer trap.