System Architecture

​

High-level overview

​

Architecture principles

​

System components

​

Applications

​

Web App (apps/web)

• Framework: Next.js 16 with React 19
• Port: 3001
• Purpose: Authenticated web console for managing skills and graph
• Key features:
  • Skill browser and editor
  • Graph visualization with D3
  • Account management
  • OAuth authentication

​

Server (apps/server)

• Framework: Hono
• Port: 3000
• Purpose: API host for Better Auth and tRPC endpoints
• Endpoints:
  • /api/auth/* - Better Auth routes
  • /trpc/* - tRPC router

​

CLI (apps/cli)

• Framework: Native Bun with @clack/prompts
• Purpose: Command-line interface for skill management
• Key features:
  • Interactive prompts
  • Local skill editing
  • tRPC client for server communication

​

Shared packages

​

API (packages/api)

• Purpose: tRPC router and business logic
• Exports:
  • AppRouter type (shared with clients)
  • tRPC procedures for skills, mentions, links
• Key concepts:
  • Procedures are the API “endpoints”
  • Context provides auth and database access
  • All domain logic lives here

// Example procedure
export const appRouter = router({
  skill: {
    list: protectedProcedure
      .query(({ ctx }) => {
        return ctx.db.query.skills.findMany({
          where: eq(skills.userId, ctx.user.id)
        });
      }),
  },
});

​

Auth (packages/auth)

• Purpose: Better Auth configuration and adapter
• Features:
  • Google and GitHub OAuth
  • Session management
  • Drizzle adapter for user storage
  • Default skills sync

​

Database (packages/db)

• Purpose: Drizzle ORM schema and migrations
• Exports:
  • Database schema definitions
  • Drizzle client instance
  • Query helpers
• Tables:
  • Users, accounts, sessions (Better Auth)
  • Skills and skill metadata
  • Graph links and mentions

​

Environment (packages/env)

• Purpose: Typed runtime environment validation
• Exports:
  • @better-skills/env/server
  • @better-skills/env/web
  • @better-skills/env/cli
• Technology: Zod schemas with T3 Env

​

Config (packages/config)

• Purpose: Shared TypeScript configuration
• Exports: Base tsconfig.json for all packages

​

Markdown (packages/markdown)

• Purpose: Markdown parsing and mention extraction
• Features:
  • Extract @mention syntax from markdown
  • Sync auto-generated links
  • Preserve manual vs. auto-generated link metadata

​

Data flow

​

Skill creation flow

​

Authentication flow

​

Request lifecycle

​

tRPC request

Client Request
    ↓
Hono Server (apps/server)
    ↓
tRPC Adapter (@hono/trpc-server)
    ↓
tRPC Context (auth + db)
    ↓
Procedure (packages/api)
    ↓
Business Logic
    ↓
Drizzle Query (packages/db)
    ↓
PostgreSQL
    ↓
Response to Client

​

Better Auth request

Client Request
    ↓
Hono Server (apps/server)
    ↓
Better Auth Handler
    ↓
Drizzle Adapter (packages/auth)
    ↓
PostgreSQL
    ↓
Session Cookie Response

​

Build system

​

Build pipeline

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    }
  }
}

• Builds run in topological order (dependencies first)
• Outputs are cached locally and remotely
• Only changed packages rebuild

​

Dependency graph

web → api → db → env
         → auth → db → env
         → markdown
server → api → ...
cli → api → ...

​

Deployment architecture

​

Production setup

​

Deployment targets

​

Key design decisions

​

Why Bun?

• Fast: 3-4x faster than Node.js for common tasks
• All-in-one: Runtime, bundler, package manager
• Native TypeScript: No transpilation needed
• Modern APIs: Web-standard APIs (fetch, etc.)

​

Why monorepo?

• Code sharing: Packages used by multiple apps
• Type safety: Shared types across all apps
• Atomic changes: Update API and clients in one PR
• Developer experience: Single repo, single install

​

Why tRPC?

• Type safety: End-to-end types from server to client
• No codegen: Types derived directly from router
• Simple: Just TypeScript functions
• Framework agnostic: Works with Next.js, CLI, React Native

​

Why Drizzle?

• TypeScript-first: Schema as code
• Lightweight: No overhead, generates clean SQL
• Migrations: Built-in migration system
• Type-safe queries: Full IntelliSense for queries

​

Security considerations

​

Next steps