HOME/PROJECTS/Hermes: API Client Foundation

Hermes: API Client Foundation

Building the robust foundation for a web-based API client focusing on OAuth, persistence, and workspace management.

versionv0.2.0 (Foundation)

authenticationBetter Auth (OAuth)

databasePostgreSQL + Prisma

deploymentDocker

Next.jsTypeScriptPostgreSQLPrismaBetter AuthTailwind CSS

SECTION 01 // THE PROBLEM

State Management in API Tools

Designing a solid foundation for workspaces, collections, and authenticated sessions before building request execution logic.

A reliable API client requires more than just making HTTP requests; it needs a structured way to organize endpoints, manage environments, and persist state securely across user sessions.

Before implementing the actual HTTP execution engine, Hermes needed a solid foundation: secure authentication, a relational schema for workspaces and collections, and a responsive frontend to manage this hierarchical data.

Stateless Clients

Lose request history and configurations when the tab closes. Require manual export/import of environments.

Persistent Workspaces

Securely store collections and environments in a relational database, tied to authenticated user accounts.

SECTION 02 // THE SOLUTION

Better Auth & Prisma Persistence

Implementing a modern web stack for secure, typed data management.

Hermes v0.2.0 establishes the core infrastructure. Authentication is handled by Better Auth, providing seamless GitHub and Google OAuth integration alongside robust session management.

Data persistence is driven by PostgreSQL and Prisma ORM, providing a type-safe schema for Users, Sessions, Workspaces, and Collections. This ensures that the application state is structurally sound before adding complex request logic.

Core Prisma Schema Model

model User {
  id            String    @id
  email         String    @unique
  name          String?
  workspaces    Workspace[]
  sessions      Session[]
}

model Workspace {
  id          String       @id @default(cuid())
  name        String
  userId      String
  user        User         @relation(fields: [userId], references: [id])
  collections Collection[]
}

model Collection {
  id          String    @id @default(cuid())
  name        String
  workspaceId String
  workspace   Workspace @relation(fields: [workspaceId], references: [id])
}

SECTION 03 // ARCHITECTURE

Foundation Architecture

The core technical pillars implemented in v0.2.0.

NODE 01

OAuth Authentication

Secure login via GitHub and Google providers using Better Auth.

Better Auth

NODE 02

Relational Schema

Type-safe database operations mapping users to their respective workspaces.

Prisma ORM

NODE 03

Persistent Storage

Robust relational data storage for collections and configurations.

PostgreSQL

NODE 04

Local Environment

Reproducible development environment orchestrating the database.

Docker Compose

SECTION 04 // DECISIONS

Architectural Choices

Laying the groundwork for a scalable developer tool.

01 // AUTHENTICATION

Better Auth over NextAuth

Chosen Architecture:Better Auth

Evaluated Alternative:NextAuth / Auth.js

Rationale:Selected Better Auth for its modern API, excellent TypeScript support, and straightforward configuration for OAuth providers and database session management.

02 // ORM

Prisma for Type Safety

Chosen Architecture:Prisma

Evaluated Alternative:Raw SQL / Drizzle

Rationale:Prisma provides excellent developer experience with its schema definition and generated TypeScript client, which is crucial for managing the complex relational hierarchies (Workspaces -> Collections -> Folders -> Requests) planned for future versions.

SECTION 05 // RETROSPECTIVE

Project Status

Current state and future roadmap for Hermes.

Foundation Complete

v0.2.0 successfully implements the core authentication and workspace management layer.

Next: Request Execution

The upcoming phases will focus on implementing the actual HTTP request builder, execution engine, and response viewer.