abraxxas

Imported from GustavEkberg/abraxxas (AGENTS.md). Install upstream with npx skills add GustavEkberg/abraxxas. Copyright stays with the author.

PROJECT KNOWLEDGE BASE

Generated: 2026-01-17 Commit: 1753789 Branch: main

OVERVIEW

Next.js 16 App Router application with Effect-TS service architecture, Drizzle ORM (PostgreSQL/Neon), better-auth authentication, nuqs URL state management, and Tailwind CSS 4.

CRITICAL RULES

• Use pnpm exclusively - not npm or yarn
• Run pnpm tsc before finishing - ensure types pass
• Run pnpm lint to check for errors - fix any issues
• Run pnpm test:run to verify tests pass - fix failures before committing

Effect-TS Rules (Enforced by ESLint)

See specs/EFFECT_BEST_PRACTICES.md for detailed explanations and alternatives.

SPECIFICATIONS

Before implementing any feature, consult specs/README.md.

• Specs describe intent; code describes reality. Check the codebase first before assuming something is/isn't implemented.
• Use specs as guidance. Follow patterns, types, and architecture defined in relevant specs.

STRUCTURE

init/
├── app/                    # Next.js App Router pages
│   ├── (auth)/             # Auth route group (login, OTP, logout)
│   ├── (dashboard)/        # Empty - future dashboard
│   └── api/                # API routes (auth catch-all, example)
├── components/ui/          # Modified shadcn/ui + custom components (see AGENTS.md)
├── lib/
│   ├── services/           # Effect-TS service layer (see AGENTS.md)
│   ├── core/               # Domain logic (each subfolder has own errors)
│   ├── next-effect/        # Effect-TS/Next.js adapter
│   ├── schemas/            # Validation schemas
│   ├── layers.ts           # AppLayer composition
│   └── utils.ts            # Utilities (cn helper)
├── instrumentation.ts      # Server-side Sentry + OTel
└── instrumentation-client.ts # Client-side PostHog + Sentry

WHERE TO LOOK

CODE MAP

CONVENTIONS

Code Style (Prettier)

• No semicolons
• No trailing commas
• Single quotes, 2-space indent, max 100 chars

File Naming

• All files use kebab-case - search-params.ts, post-list.tsx, live-layer.ts
• Server actions end in -action.ts - delete-post-action.ts
• URL state definitions - search-params.ts in the route directory

Effect-TS Service Pattern

// Services use static layer/Live properties for v4 compatibility
export class ServiceName extends Effect.Service<ServiceName>()('@app/ServiceName', {
  effect: Effect.gen(function* () {
    /* ... */
  })
}) {
  static layer = this.Default
  static Live = this.layer.pipe(Layer.provide(ConfigLive))
}

Configuration

• Always use Config.string('VAR') or Config.redacted('SECRET')
• Never use process.env directly with throws

Required Environment Variables:

Observability

• All service methods: Effect.withSpan('Service.method')
• Error logging: Effect.tapError()
• Span attributes: Effect.annotateCurrentSpan()

Imports

• Use @/ path alias for project imports
• No barrel files - import directly from source files
• Import services from live-layer.ts directly

ANTI-PATTERNS (THIS PROJECT)

UNIQUE STYLES

Next.js + Effect Integration

Pages use NextEffect.runPromise() which catches RedirectError and calls redirect() outside the Effect context. This is required because Next.js redirects must be called outside try-catch.

UI Components

Uses Base UI (@base-ui/react) primitives instead of Radix UI. Components are shadcn-styled but built on a different foundation. See components/ui/AGENTS.md.

Service Dependency Hierarchy

AppLayer
├── Auth.Live → Email.Live
├── Db.Live
├── S3.Live
├── Sprites.Live
├── Telegram.Live
├── Activity.Live → Telegram.Live
└── TelemetryLayer

Data Access Patterns

See specs/DATA_ACCESS_PATTERNS.md for full details. Summary:

Server Action Pattern:

// lib/core/post/delete-post-action.ts
'use server'

export const deletePostAction = async (postId: Post['id']) => {
  return await NextEffect.runPromise(
    Effect.gen(function* () {
      const session = yield* getSession()
      yield* deletePost(postId)
    }).pipe(
      Effect.withSpan('action.post.delete'),
      Effect.provide(AppLayer),
      Effect.scoped,
      Effect.matchEffect({
        onFailure: error => /* handle errors */,
        onSuccess: () => Effect.sync(() => revalidatePath('/posts'))
      })
    )
  )
}

NOTES

• No CI/CD configured - deployment via Vercel auto-deploy
• React Compiler enabled - automatic memoization (experimental)
• PostHog proxied - requests via /ph/* rewrites to bypass ad-blockers
• Drizzle beta - using 1.0.0-beta.11, may have breaking changes
• Effect v4 migration: services designed for easy Effect.Service → ServiceMap.Service transition

SUBDIRECTORY DOCS

• lib/services/AGENTS.md - Effect-TS service architecture patterns
• components/ui/AGENTS.md - UI component patterns and customizations