<root>/
├── package.json            # workspaces + aggregate scripts
├── eslint.config.js        # flat config, root-only
├── prettier.config.js      # root-only
├── .prettierignore .gitignore .env.example
├── dev.sh                  # full local stack, port-derived
├── .conductor/settings.toml
├── .vscode/{settings,extensions}.json
├── AGENTS.md CLAUDE.md README.md
├── apps/
│   ├── api/     # Bun + Elysia modular monolith, exports `type App`
│   ├── web/     # Vite + React + Tailwind v4 + coss UI + lucide-react
│   └── worker/  # Bun long-running loop (indexer/outbox/cron)
├── packages/
│   ├── shared/  # zod schemas, env schema+loader, logger, pure domain logic
│   └── db/      # drizzle schema, migrations, seed/backfill scripts
├── edge-worker/ # optional; Cloudflare Worker, NOT a workspace (own lockfile)
└── docs/{adr,runbooks}/

{
  "name": "@<proj>/root",
  "private": true,
  "type": "module",
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "lint": "bun run --workspaces lint:fix",
    "eslint": "bun run --workspaces lint",
    "format": "bun run --workspaces format",
    "format:check": "bun run --workspaces format:check",
    "typecheck": "bun run --workspaces typecheck",
    "test": "bun run --filter '@<proj>/shared' --filter '@<proj>/api' test",
    "check": "F=0; bun run lint || F=1; bun run format || F=1; bun run typecheck || F=1; bun run test || F=1; exit $F",
    "db:generate": "bun run --filter '@<proj>/db' db:generate",
    "db:migrate": "bun run --filter '@<proj>/db' db:migrate",
    "dev:api": "bun run --filter '@<proj>/api' dev",
    "dev:web": "bun run --filter '@<proj>/web' dev"
  },
  "devDependencies": {
    "@eslint/js": "latest",
    "@types/bun": "latest",
    "eslint": "latest",
    "eslint-config-prettier": "latest",
    "eslint-plugin-react-hooks": "latest",
    "eslint-plugin-simple-import-sort": "latest",
    "eslint-plugin-unused-imports": "latest",
    "globals": "latest",
    "prettier": "latest",
    "prettier-plugin-tailwindcss": "latest",
    "typescript": "latest",
    "typescript-eslint": "latest"
  }
}

import eslint from "@eslint/js";
import eslintConfigPrettier from "eslint-config-prettier";
import reactHooks from "eslint-plugin-react-hooks";
import simpleImportSort from "eslint-plugin-simple-import-sort";
import unusedImports from "eslint-plugin-unused-imports";
import globals from "globals";
import tseslint from "typescript-eslint";

export default tseslint.config(
  { ignores: ["**/node_modules/**", "**/dist/**", "**/coverage/**", "apps/web/public/**"] },
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  eslintConfigPrettier,
  {
    rules: {
      "padding-line-between-statements": [
        "error",
        { blankLine: "always", prev: "*", next: "return" },
      ],
    },
  },
  {
    files: ["apps/**/*.{ts,tsx}", "packages/**/*.ts"],
    plugins: { "simple-import-sort": simpleImportSort, "unused-imports": unusedImports },
    rules: {
      "simple-import-sort/imports": "error",
      "simple-import-sort/exports": "error",
      "@typescript-eslint/no-unused-vars": "off",
      "unused-imports/no-unused-imports": "error",
      "unused-imports/no-unused-vars": [
        "warn",
        { vars: "all", varsIgnorePattern: "^_", args: "after-used", argsIgnorePattern: "^_" },
      ],
      "@typescript-eslint/ban-ts-comment": [
        "error",
        { "ts-nocheck": "allow-with-description", minimumDescriptionLength: 10 },
      ],
    },
  },
  {
    files: ["apps/**/*.{ts,tsx}", "packages/**/*.ts"],
    // The shared logger is the only sanctioned writer (§4).
    ignores: ["packages/shared/src/logger/browser.ts"],
    rules: { "no-console": "error" },
  },
  {
    files: ["apps/api/**/*.ts", "apps/worker/**/*.ts", "packages/**/*.ts"],
    languageOptions: { globals: { ...globals.node, ...globals.es2021, Bun: "readonly" } },
  },
  {
    files: ["apps/web/**/*.{ts,tsx}"],
    plugins: { "react-hooks": reactHooks },
    rules: { ...reactHooks.configs["recommended-latest"].rules },
    languageOptions: { globals: { ...globals.browser, ...globals.es2021 } },
  },
);

/** @type {import("prettier").Config} */
export default {
  semi: true,
  singleQuote: false,
  trailingComma: "all",
  printWidth: 100,
  tabWidth: 2,
  plugins: ["prettier-plugin-tailwindcss"],
  tailwindStylesheet: "./apps/web/src/styles.css",
};

node_modules
.eslintcache
.DS_Store
dist
out
coverage

`.vscode/settings.json`: `editor.formatOnSave`, default formatter
`esbenp.prettier-vscode`, `editor.codeActionsOnSave: {"source.fixAll.eslint": "explicit"}`,
`eslint.useFlatConfig: true`, `prettier.requireConfig: true`.
`.vscode/extensions.json`: recommend `dbaeumer.vscode-eslint`, `esbenp.prettier-vscode`.

{
  "compilerOptions": {
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "types": ["bun"],
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  },
  "include": ["src/**/*.ts"]
}

"exports": {
  ".": "./src/index.ts",
  "./config": "./src/config/index.ts",
  "./logger": {
    "browser": "./src/logger/browser.ts",
    "default": "./src/logger/server.ts"
  },
  "./schemas": "./src/schemas/index.ts"
}

import fs from "node:fs";
import path from "node:path";

import { parse as parseDotenv } from "dotenv";

const stripExportPrefixes = (raw: string) => raw.replace(/^\s*export\s+/gm, "");

const loadEnvFile = (filePath: string): void => {
  if (!fs.existsSync(filePath)) return;
  const parsed = parseDotenv(stripExportPrefixes(fs.readFileSync(filePath, "utf8")));
  for (const [key, value] of Object.entries(parsed)) {
    if (process.env[key] === undefined) process.env[key] = value;
  }
};

export const loadEnvFiles = (paths: string[]): void => {
  for (const filePath of paths) loadEnvFile(filePath);
};

apps/api/src/config/env.ts        apiEnvSchema      -> export const env
apps/worker/src/config/env.ts     workerEnvSchema   -> export const env (+ config)
packages/db/src/config/env.ts     dbEnvSchema       -> export const env
packages/shared/src/config/env-schema.ts            -> shared slice, no parse
apps/web/src/config/index.ts      import.meta.env   -> export const config
packages/db/drizzle.config.ts     own loader        -> runs outside the app

import path from "node:path";

import { loadEnvFiles, sharedEnvSchema } from "@<proj>/shared/config";
import { z } from "zod";

const appDir = path.resolve(import.meta.dir, "..", "..");
const rootDir = path.resolve(appDir, "..", "..");

loadEnvFiles([
  path.join(appDir, ".env.local"),
  path.join(appDir, ".env"),
  path.join(rootDir, ".env.local"),
  path.join(rootDir, ".env"),
]);

const apiEnvSchema = sharedEnvSchema.extend({
  NODE_ENV: z.string().default("development"),
  PORT: z.coerce.number().int().positive().default(4000),
  HOST: z.string().min(1).default("0.0.0.0"),
  DATABASE_URL: z.string().min(1),
  BETTER_AUTH_SECRET: z.string().min(1),
  /** Public SPA origin. No trailing slash — normalized here, not at call sites. */
  CORS_ORIGIN: z
    .string()
    .min(1)
    .default("http://localhost:5174")
    .transform((v) => v.replace(/^["']+|["']+$/g, "").trim().replace(/\/+$/, "")),
});

const parsed = apiEnvSchema.safeParse(process.env);
if (!parsed.success) {
  const details = parsed.error.issues
    .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
    .join("; ");
  throw new Error(`Invalid API environment configuration: ${details}`);
}

export const env = parsed.data;

const optionalSecret = z
  .string()
  .trim()
  .transform((v) => (v.length > 0 ? v : undefined))
  .optional();

export const publicFightersQuerySchema = z.object({
  sort: z.enum(["latest", "wins", "rating"]).optional(),
  limit: z.coerce.number().int().min(1).max(100).default(30),
});
export type PublicFightersQuery = z.infer<typeof publicFightersQuerySchema>;

export const publicFightersResponseSchema = z.object({ fighters: z.array(publicFighterSchema) });
export type PublicFightersResponse = z.infer<typeof publicFightersResponseSchema>;

export type LogFields = Record<string, unknown>;

export interface Logger {
  trace(fields: LogFields, msg?: string): void;
  debug(fields: LogFields, msg?: string): void;
  info(fields: LogFields, msg?: string): void;
  warn(fields: LogFields, msg?: string): void;
  error(fields: LogFields, msg?: string): void;
  child(bindings: LogFields): Logger;
}

import pino from "pino";
import type { Logger } from "./types";

// Reads the shared env slice — the logger is a config consumer like any other
// module, it never touches process.env itself (§3).
import { env } from "../config";

export const logger: Logger = pino({
  level: env.LOG_LEVEL,
  base: { service: env.SERVICE_NAME, env: env.NODE_ENV },
  // Redaction is structural, not per-call-site: assume someone will eventually
  // log a whole request or config object, and make that safe in advance.
  redact: {
    paths: [
      "req.headers.authorization",
      "req.headers.cookie",
      "*.password",
      "*.token",
      "*.secret",
      "*.privateKey",
    ],
    censor: "[redacted]",
  },
  // Prod emits raw NDJSON for the collector; dev gets a human transport.
  transport:
    env.NODE_ENV === "development"
      ? { target: "pino-pretty", options: { colorize: true, translateTime: "HH:MM:ss" } }
      : undefined,
});

import type { Logger, LogFields } from "./types";

// Dev: everything. Prod: warn and error only.
const MIN_LEVEL = import.meta.env?.DEV ? 0 : 3;

const make = (bindings: LogFields): Logger => {
  const emit =
    (level: number, method: "debug" | "info" | "warn" | "error") =>
    (fields: LogFields, msg?: string) => {
      if (level < MIN_LEVEL) return;
      // eslint-disable-next-line no-console -- the single sanctioned console writer
      console[method](msg ?? "", { ...bindings, ...fields });
    };

  return {
    trace: emit(0, "debug"),
    debug: emit(1, "debug"),
    info: emit(2, "info"),
    warn: emit(3, "warn"),
    error: emit(4, "error"),
    child: (extra) => make({ ...bindings, ...extra }),
  };
};

export const logger = make({});

"./logger": {
  "browser": "./src/logger/browser.ts",
  "default": "./src/logger/server.ts"
}

LOG_LEVEL: z.enum(["trace", "debug", "info", "warn", "error"]).default("info"),
SERVICE_NAME: z.string().min(1).default("api"), // shows up as `service` on every line

// apps/api/src/plugins/logging.ts
import { Elysia } from "elysia";
import { logger } from "@<proj>/shared/logger";

export const loggingPlugin = new Elysia({ name: "logging" })
  .derive({ as: "global" }, ({ request, set }) => {
    // Honour an inbound id so a trace survives across services; echo it back so
    // a user can quote it in a bug report and land on the exact request.
    const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();
    set.headers["x-request-id"] = requestId;

    return {
      log: logger.child({
        requestId,
        method: request.method,
        path: new URL(request.url).pathname,
      }),
    };
  })
  .onAfterResponse({ as: "global" }, ({ log, set }) => {
    log.info({ status: set.status }, "request");
  })
  .onError({ as: "global" }, ({ log, code, error }) => {
    log.error(
      { code, err: error instanceof Error ? { message: error.message, stack: error.stack } : error },
      "unhandled",
    );
  });

{
  files: ["apps/**/*.{ts,tsx}", "packages/**/*.ts"],
  ignores: ["packages/shared/src/logger/browser.ts"],
  rules: { "no-console": "error" },
},