Skip to content

server tracing #420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ publish
output
# generated prisma client
apps/server/prisma/generated/
apps/server-new/prisma/generated/

# Logs
logs
Expand Down
16 changes: 16 additions & 0 deletions apps/server-new/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Server Configuration
PORT=3030

# Database
DATABASE_URL=file:./dev.db

# Privy Configuration
PRIVY_APP_ID=your_privy_app_id
PRIVY_APP_SECRET=your_privy_app_secret

# Hypergraph Configuration
HYPERGRAPH_CHAIN=geo-testnet
HYPERGRAPH_RPC_URL=

# Honeycomb Configuration
HONEYCOMB_API_KEY=
191 changes: 191 additions & 0 deletions apps/server-new/CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Package Management
**Important**: Use pnpm for package management.
- `pnpm install` - Install dependencies
- `pnpm add <package>` - Add new dependency
- `pnpm remove <package>` - Remove dependency

### Build and Run
- `pnpm dev` - Start development server with hot reload ⚠️ **DO NOT USE** - Never run dev mode during development
- `pnpm start` - Run the application in production mode
- `pnpm build` - Build the project for production (outputs to ./dist)

**IMPORTANT**: Never run `pnpm dev` during development work. The development server should only be started by the user manually when they want to test the application. Use tests instead of running the dev server.

### Code Quality
- `pnpm typecheck` - Run TypeScript type checking without emitting files
- `pnpm lint` - Run Biome on all TypeScript/JavaScript files
- `pnpm lint:fix` - Run Biome with automatic fixes on all files

### Testing
- `pnpm test` - Run all tests once
- `pnpm test:watch` - Run tests in watch mode
- Uses Vitest with @effect/vitest for Effect-aware testing
- Test files: `test/**/*.test.ts` and `src/**/*.test.ts`

### Database
- `pnpm prisma generate` - Generate Prisma client
- `pnpm prisma migrate dev` - Run database migrations in development
- `pnpm prisma studio` - Open Prisma Studio GUI

**CRITICAL DEVELOPMENT RULE**: After EVERY file change, you MUST:
1. Run `pnpm lint:fix` immediately
2. Run `pnpm typecheck` immediately
3. Fix ALL lint errors and type errors before proceeding
4. Do NOT continue development until both commands pass without errors

This is non-negotiable and applies to every single file modification.

## Project Architecture

### Technology Stack
- **Runtime**: Node.js with tsx for development
- **Language**: TypeScript with ES2022 target
- **Framework**: Effect Platform HTTP API
- **Database**: SQLite with Prisma ORM
- **Authentication**: Privy for external auth, custom session tokens for internal

### Code Style
- Uses Biome for linting and formatting (monorepo configuration)
- Line width: 120 characters, 2-space indentation
- Single quotes for JavaScript/TypeScript

### TypeScript Configuration
- Strict mode enabled
- Effect patterns preferred (Effect.fn over Effect.gen)
- No emit configuration (build handled by tsup)
- Path aliases configured: `server-new/*` maps to `./src/*`

### Project Structure
- `src/` - Source code directory
- `config/` - Configuration modules
- `http/` - HTTP API definitions and handlers
- `services/` - Business logic services
- `domain/` - Domain models (Effect Schema)
- `prisma/` - Database schema and migrations
- `test/` - Test files
- `specs/` - Feature specifications
- `patterns/` - Implementation patterns documentation

## Development Workflow - Spec-Driven Development

This project follows a **spec-driven development** approach where every feature is thoroughly specified before implementation.

**CRITICAL RULE: NEVER IMPLEMENT WITHOUT FOLLOWING THE COMPLETE SPEC FLOW**

### Mandatory Workflow Steps

**AUTHORIZATION PROTOCOL**: Before proceeding to any phase (2-5), you MUST:
1. Present the completed work from the current phase
2. Explicitly ask for user authorization to proceed
3. Wait for clear user approval before continuing
4. NEVER assume permission or proceed automatically

### Phase-by-Phase Process

**Phase 1**: Create `instructions.md` (initial requirements capture)
- Create feature folder and capture user requirements
- Document user stories, acceptance criteria, constraints

**Phase 2**: Derive `requirements.md` from instructions - **REQUIRES USER APPROVAL**
- Structured analysis of functional/non-functional requirements
- STOP and ask for authorization before proceeding to Phase 3

**Phase 3**: Create `design.md` from requirements - **REQUIRES USER APPROVAL**
- Technical design and implementation strategy
- STOP and ask for authorization before proceeding to Phase 4

**Phase 4**: Generate `plan.md` from design - **REQUIRES USER APPROVAL**
- Implementation roadmap and task breakdown
- STOP and ask for authorization before proceeding to Phase 5

**Phase 5**: Execute implementation - **REQUIRES USER APPROVAL**
- Follow the plan exactly as specified
- NEVER start implementation without explicit user approval

## Effect TypeScript Development Patterns

### Core Principles
- **Type Safety First**: Never use `any` or type assertions - prefer explicit types
- **Effect Patterns**: Use Effect's composable abstractions (prefer Effect.fn)
- **Early Returns**: Prefer early returns over deep nesting
- **Input Validation**: Validate inputs at system boundaries with Effect Schema
- **Resource Safety**: Use Effect's resource management for automatic cleanup

### Effect-Specific Patterns

#### Sequential Operations (Effect.fn preferred)
```typescript
// Use Effect.fn for sequential operations
const program = Effect.fn(function* () {
const user = yield* getUser(id)
const profile = yield* getProfile(user.profileId)
return { user, profile }
})
```

#### Error Handling
```typescript
// Use Data.TaggedError for custom errors
class UserNotFound extends Data.TaggedError("UserNotFound")<{
readonly id: string
}> {}

// Use Effect.tryPromise for Promise integration
const fetchUser = (id: string) =>
Effect.tryPromise({
try: () => prisma.user.findUniqueOrThrow({ where: { id } }),
catch: () => new UserNotFound({ id })
})
```

#### Testing with @effect/vitest

**Use @effect/vitest for Effect code:**
- Import pattern: `import { assert, describe, it } from "@effect/vitest"`
- Test pattern: `it.effect("description", () => Effect.fn(function*() { ... }))`
- **FORBIDDEN**: Never use `expect` from vitest in Effect tests - use `assert` methods

#### Correct it.effect Pattern

```typescript
import { assert, describe, it } from "@effect/vitest"
import { Effect } from "effect"

describe("UserService", () => {
it.effect("should fetch user successfully", () =>
Effect.fn(function* () {
const user = yield* fetchUser("123")

// Use assert methods, NOT expect
assert.strictEqual(user.id, "123")
assert.deepStrictEqual(user.profile, expectedProfile)
assert.isTrue(user.active)
}))
})
```

## Implementation Patterns

The project includes comprehensive pattern documentation for future reference and consistency:

### Pattern Directory
**Location**: `patterns/`
- **Purpose**: Detailed documentation of all implementation patterns used in the project
- **Usage**: Reference material for maintaining consistency and best practices

### Available Patterns
- **http-api.md**: HTTP API definition and implementation patterns
- **layer-composition.md**: Layer-based dependency injection patterns
- **generic-testing.md**: General testing patterns with @effect/vitest

## Notes
- This is an Effect Platform HTTP API migration of the original Express server
- Focus on type safety, observability, and error handling
- WebSocket functionality excluded (to be migrated separately)
- Uses hardcoded port configuration (no portfinder)
37 changes: 37 additions & 0 deletions apps/server-new/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
{
"name": "server-new",
"version": "0.1.0",
"private": true,
"type": "module",
"scripts": {
"dev": "tsx watch ./src/index.ts",
"start": "node ./dist/index.js",
"build": "tsup",
"test": "vitest run",
"test:watch": "vitest",
"typecheck": "tsc --noEmit",
"lint": "biome check",
"lint:fix": "biome check --write --unsafe",
"prisma": "prisma",
"prebuild": "prisma generate"
},
"dependencies": {
"@effect/opentelemetry": "^0.56.0",
"@effect/platform": "^0.90.0",
"@effect/platform-node": "^0.94.0",
"@graphprotocol/hypergraph": "workspace:*",
"@prisma/client": "^6.7.0",
"@privy-io/server-auth": "^1.26.0",
"cors": "^2.8.5",
"effect": "^3.17.3"
},
"devDependencies": {
"@types/cors": "^2.8.17",
"@types/node": "^24.1.0",
"prisma": "^6.7.0",
"tsup": "^8.4.0",
"tsx": "^4.19.0",
"typescript": "^5.8.3",
"vitest": "^3.2.4"
}
}
19 changes: 19 additions & 0 deletions apps/server-new/patterns/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Implementation Patterns

This directory contains detailed documentation of implementation patterns used throughout the project. These patterns provide reusable solutions and best practices for Effect TypeScript development.

## Patterns

- **[http-api.md](./http-api.md)** - HTTP API definition and implementation patterns using Effect platform
- **[layer-composition.md](./layer-composition.md)** - Layer-based dependency injection and service composition patterns
- **[generic-testing.md](./generic-testing.md)** - General testing patterns with @effect/vitest and Effect ecosystem

## Usage

Each pattern document includes:
- Core concepts and principles
- Code examples from the implementation
- Best practices and guidelines
- Common pitfalls to avoid

These patterns serve as reference material for future development and help maintain consistency across the codebase.
Loading
Loading