refactor: migrate backend to pnpm monorepo with Hono module architecture

- Replace Bun with pnpm 9 + Turborepo + tsx; apps/api renamed to apps/backend
- Split backend into http/, modules/, lib/ layers mirroring tai-specguard
- Add use-case + Result pattern, Problem Details RFC 7807, basePath /api/v1
- Mount Better Auth at /api/v1/auth, keep session-auth whitelist
- Split Prisma schema into prisma/models/*, generate into generated/
- Rework packages/shared into lib/ + schemas/ with pagination DTOs
- Implement health, groups, students, payments, waitlist modules
- Add vitest suite with prisma mocks (21 tests), biome lint
- Point web client to /api/v1/auth and /api/v1/groups/from-organization

apps/backend/src/app.ts

@@ -0,0 +1,49 @@
+import { Hono } from 'hono';
+import type { BackendEnv } from '@/http/env';
+import {
+  internalServerErrorProblem,
+  notFoundProblem,
+  problemJson,
+} from '@/http/problem-details';
+import { requestIdMiddleware } from '@/http/request-id';
+import { requestLoggerMiddleware } from '@/http/request-logger';
+import { corsMiddleware, securityHeadersMiddleware } from '@/http/security-headers';
+import { sessionAuthMiddleware } from '@/http/session-auth';
+import { logger } from '@/logger';
+import { authRoutes } from './modules/auth';
+import { groupsRoutes } from './modules/groups';
+import { healthCheckRoutes } from './modules/health-check';
+import { paymentsRoutes } from './modules/payments';
+import { studentsRoutes } from './modules/students';
+import { waitlistRoutes } from './modules/waitlist';
+
+const app = new Hono<BackendEnv>();
+
+app.use('*', corsMiddleware);
+app.use('*', securityHeadersMiddleware);
+app.use('*', requestIdMiddleware);
+app.use('*', requestLoggerMiddleware);
+
+app.get('/', (c) => c.json({ name: 'Gruperly API', status: 'ok' }));
+
+const api = app.basePath('/api/v1');
+
+api.use('*', sessionAuthMiddleware);
+
+api.route('/auth', authRoutes);
+api.route('/health', healthCheckRoutes);
+api.route('/groups', groupsRoutes);
+api.route('/students', studentsRoutes);
+api.route('/payments', paymentsRoutes);
+api.route('/waitlist', waitlistRoutes);
+
+app.notFound((c) => {
+  return problemJson(c, notFoundProblem(c.req.path));
+});
+
+app.onError((error, c) => {
+  logger.error({ error, path: c.req.path }, 'Unhandled request error');
+  return problemJson(c, internalServerErrorProblem(c.req.path));
+});
+
+export default app;

apps/backend/src/http/env.ts

@@ -0,0 +1,19 @@
+import type { auth } from '@/modules/auth/auth';
+
+type AuthSession = typeof auth.$Infer.Session;
+
+export type BackendEnv = {
+  Variables: {
+    user: AuthSession['user'] | null;
+    session: AuthSession['session'] | null;
+    requestId: string;
+  };
+};
+
+declare module 'hono' {
+  interface ContextVariableMap {
+    user: AuthSession['user'] | null;
+    session: AuthSession['session'] | null;
+    requestId: string;
+  }
+}

apps/backend/src/http/problem-builders.ts

@@ -0,0 +1,89 @@
+import type { ProblemDetails } from '@gruperly/shared';
+import { notFoundProblem } from './problem-details';
+import { PROBLEM_DOMAIN } from './problem-domain';
+
+export function validationProblem(params: {
+  detail?: string;
+  instance?: string;
+  errors?: Record<string, string[]>;
+}): ProblemDetails {
+  return {
+    type: `${PROBLEM_DOMAIN}/problems/validation`,
+    title: 'Bad Request',
+    status: 400,
+    detail: params.detail ?? 'Invalid request data',
+    instance: params.instance,
+    errors: params.errors,
+  };
+}
+
+export function conflictProblem(params: {
+  detail: string;
+  code?: string;
+  instance?: string;
+}): ProblemDetails {
+  return {
+    type: `${PROBLEM_DOMAIN}/problems/conflict`,
+    title: 'Conflict',
+    status: 409,
+    detail: params.detail,
+    instance: params.instance,
+    code: params.code,
+  };
+}
+
+export function forbiddenProblem(params: {
+  detail: string;
+  code?: string;
+  instance?: string;
+}): ProblemDetails {
+  return {
+    type: `${PROBLEM_DOMAIN}/problems/forbidden`,
+    title: 'Forbidden',
+    status: 403,
+    detail: params.detail,
+    instance: params.instance,
+    code: params.code,
+  };
+}
+
+export function organizationNotFoundProblem(id: string): ProblemDetails {
+  return {
+    type: `${PROBLEM_DOMAIN}/problems/organization-not-found`,
+    title: 'Not Found',
+    status: 404,
+    detail: `Organization ${id} was not found.`,
+    code: 'organization_not_found',
+  };
+}
+
+export function groupOwnerRequiredProblem(): ProblemDetails {
+  return forbiddenProblem({
+    detail: 'Only the organization owner can create the group.',
+    code: 'group_owner_required',
+  });
+}
+
+export function databaseUnavailableProblem(params?: {
+  instance?: string;
+}): ProblemDetails {
+  return {
+    type: `${PROBLEM_DOMAIN}/problems/database-unavailable`,
+    title: 'Service Unavailable',
+    status: 503,
+    detail: 'Database health check failed',
+    instance: params?.instance,
+    code: 'database_unavailable',
+  };
+}
+
+export function noGroupAccessProblem(): ProblemDetails {
+  return forbiddenProblem({
+    detail: 'You do not have access to this group.',
+    code: 'group_access_denied',
+  });
+}
+
+export function notFoundResourceProblem(resourceName: string, id: string): ProblemDetails {
+  return notFoundProblem(`${resourceName} ${id}`);
+}

apps/backend/src/http/problem-details.ts

@@ -0,0 +1,82 @@
+import type { ProblemDetails, Result } from '@gruperly/shared';
+import type { Context } from 'hono';
+import type {
+  ClientErrorStatusCode,
+  ServerErrorStatusCode,
+  SuccessStatusCode,
+} from 'hono/utils/http-status';
+
+type ProblemStatusCode = ClientErrorStatusCode | ServerErrorStatusCode;
+type JsonSuccessStatusCode = Exclude<SuccessStatusCode, 204 | 205>;
+
+type ProblemDetailsInput = Omit<ProblemDetails, 'status' | 'title'> & {
+  status: ProblemStatusCode;
+  title: string;
+};
+
+type ResultJsonOptions = {
+  status?: JsonSuccessStatusCode;
+};
+
+const DEFAULT_TYPE = 'about:blank';
+
+export const problemDetails = ({
+  type = DEFAULT_TYPE,
+  title,
+  status,
+  detail,
+  instance,
+  code,
+}: ProblemDetailsInput): ProblemDetails => ({
+  type,
+  title,
+  status,
+  ...(detail ? { detail } : {}),
+  ...(instance ? { instance } : {}),
+  ...(code ? { code } : {}),
+});
+
+export const problemJson = (c: Context, problem: ProblemDetails) => {
+  return c.json(problem, problem.status as ProblemStatusCode, {
+    'Content-Type': 'application/problem+json',
+  });
+};
+
+export const resultJson = <TValue>(
+  c: Context,
+  result: Result<TValue, ProblemDetails>,
+  { status = 200 }: ResultJsonOptions = {},
+) => {
+  if (!result.ok) {
+    return problemJson(c, result.error);
+  }
+
+  return c.json(result.value, status);
+};
+
+export const notFoundProblem = (instance: string): ProblemDetails =>
+  problemDetails({
+    title: 'Not Found',
+    status: 404,
+    detail: 'The requested resource was not found.',
+    instance,
+    code: 'not_found',
+  });
+
+export const internalServerErrorProblem = (instance: string): ProblemDetails =>
+  problemDetails({
+    title: 'Internal Server Error',
+    status: 500,
+    detail: 'An unexpected error occurred.',
+    instance,
+    code: 'internal_server_error',
+  });
+
+export const unauthorizedProblem = (instance: string): ProblemDetails =>
+  problemDetails({
+    title: 'Unauthorized',
+    status: 401,
+    detail: 'Authentication is required to access this resource.',
+    instance,
+    code: 'unauthorized',
+  });

apps/backend/src/http/problem-domain.ts

@@ -0,0 +1 @@
+export const PROBLEM_DOMAIN = process.env.PROBLEM_DOMAIN_URL ?? 'https://gruperly.com';

apps/backend/src/http/request-id.ts

@@ -0,0 +1,12 @@
+import type { MiddlewareHandler } from 'hono';
+import { runWithRequestLogContext } from '@/logger';
+import type { BackendEnv } from './env';
+
+export const requestIdMiddleware: MiddlewareHandler<BackendEnv> = async (c, next) => {
+  const requestId = crypto.randomUUID();
+
+  c.set('requestId', requestId);
+  c.header('X-Request-Id', requestId);
+
+  await runWithRequestLogContext(requestId, next);
+};

apps/backend/src/http/request-logger.ts

@@ -0,0 +1,22 @@
+import type { MiddlewareHandler } from 'hono';
+import { logger } from '@/logger';
+import type { BackendEnv } from './env';
+
+export const requestLoggerMiddleware: MiddlewareHandler<BackendEnv> = async (c, next) => {
+  const startedAt = Date.now();
+
+  try {
+    await next();
+  } finally {
+    logger.info(
+      {
+        method: c.req.method,
+        path: c.req.path,
+        requestId: c.get('requestId'),
+        status: c.res.status,
+        durationMs: Date.now() - startedAt,
+      },
+      'Request completed',
+    );
+  }
+};

apps/backend/src/http/security-headers.ts

@@ -0,0 +1,34 @@
+import type { MiddlewareHandler } from 'hono';
+import { cors as honoCors } from 'hono/cors';
+
+function getWebOrigin(): string {
+  return process.env.WEB_URL ?? 'http://localhost:6173';
+}
+
+export const corsMiddleware: MiddlewareHandler = honoCors({
+  origin: (requestOrigin) => {
+    const allowed = getWebOrigin();
+    if (requestOrigin === allowed) {
+      return requestOrigin;
+    }
+    return '';
+  },
+  allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowHeaders: ['Content-Type', 'Authorization'],
+  maxAge: 600,
+  credentials: true,
+});
+
+export const securityHeadersMiddleware: MiddlewareHandler = async (c, next) => {
+  await next();
+
+  c.header('X-Content-Type-Options', 'nosniff');
+  c.header('X-Frame-Options', 'DENY');
+  c.header('X-XSS-Protection', '0');
+  c.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+  c.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+
+  if (process.env.NODE_ENV === 'production') {
+    c.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+  }
+};

apps/backend/src/http/session-auth.ts

@@ -0,0 +1,43 @@
+import type { MiddlewareHandler } from 'hono';
+import { auth } from '@/modules/auth/auth';
+import type { BackendEnv } from './env';
+import { problemJson, unauthorizedProblem } from './problem-details';
+
+export const sessionAuthMiddleware: MiddlewareHandler<BackendEnv> = async (c, next) => {
+  if (isPublicApiRequest(c.req.method, c.req.path)) {
+    await next();
+    return;
+  }
+
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+  if (!session) {
+    return problemJson(c, unauthorizedProblem(c.req.path));
+  }
+
+  c.set('user', session.user);
+  c.set('session', session.session);
+
+  await next();
+};
+
+export function isPublicApiRequest(method: string, path: string): boolean {
+  if (method === 'OPTIONS') {
+    return true;
+  }
+
+  const normalizedPath = normalizePath(path);
+
+  return (
+    normalizedPath === '/api/v1/health'
+    || matchesPublicPrefix(normalizedPath, '/api/v1/auth')
+    || matchesPublicPrefix(normalizedPath, '/api/auth')
+  );
+}
+
+function matchesPublicPrefix(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+function normalizePath(path: string): string {
+  return path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
+}

apps/backend/src/http/validate.ts

@@ -0,0 +1,57 @@
+import { zValidator } from '@hono/zod-validator';
+import type { Context } from 'hono';
+import type { ZodIssue, ZodSchema } from 'zod';
+import { validationProblem } from './problem-builders';
+import { zodIssuesToRecord } from './zod-issues';
+
+type ValidationTarget = 'json' | 'query' | 'param' | 'header' | 'form';
+
+function makeValidator(target: ValidationTarget, schema: ZodSchema) {
+  return zValidator(
+    target,
+    schema,
+    (result: { success: boolean; error?: { issues: ZodIssue[] } }, c: Context) => {
+      if (result.success) {
+        return;
+      }
+
+      const requestId = c.get('requestId');
+      const instance = requestId ? `/requests/${requestId}` : undefined;
+      const issues = result.error?.issues ?? [];
+
+      return c.json(
+        validationProblem({
+          detail: `Invalid ${target} data`,
+          instance,
+          errors: zodIssuesToRecord(issues),
+        }),
+        400,
+        {
+          'Content-Type': 'application/problem+json',
+        },
+      );
+    },
+  );
+}
+
+export const validate = {
+  json(schema: ZodSchema) {
+    return makeValidator('json', schema);
+  },
+
+  query(schema: ZodSchema) {
+    return makeValidator('query', schema);
+  },
+
+  param(schema: ZodSchema) {
+    return makeValidator('param', schema);
+  },
+
+  header(schema: ZodSchema) {
+    return makeValidator('header', schema);
+  },
+
+  form(schema: ZodSchema) {
+    return makeValidator('form', schema);
+  },
+};

apps/backend/src/http/zod-issues.ts

@@ -0,0 +1,16 @@
+type IssueLike = {
+  path: PropertyKey[];
+  message: string;
+};
+
+export function zodIssuesToRecord(issues: IssueLike[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+
+  for (const issue of issues) {
+    const key = issue.path.length ? issue.path.join('.') : 'root';
+    out[key] ??= [];
+    out[key].push(issue.message);
+  }
+
+  return out;
+}

apps/backend/src/lib/email.ts

@@ -0,0 +1,94 @@
+import nodemailer, { type Transporter } from 'nodemailer'
+
+type VerificationEmailData = { email: string; url: string; name?: string }
+type PasswordResetEmailData = { email: string; url: string; name?: string }
+type InvitationEmailData = { email: string; url: string; organizationName: string }
+
+interface EmailProvider {
+  sendVerificationEmail(data: VerificationEmailData): Promise<void>
+  sendPasswordResetEmail(data: PasswordResetEmailData): Promise<void>
+  sendOrganizationInvitation(data: InvitationEmailData): Promise<void>
+}
+
+class SMTPEmailProvider implements EmailProvider {
+  private transporter: Transporter
+
+  constructor() {
+    this.transporter = nodemailer.createTransport({
+      host: process.env.EMAIL_SERVER_HOST,
+      port: Number(process.env.EMAIL_SERVER_PORT ?? 587),
+      secure: (process.env.EMAIL_SERVER_PORT ?? '587') === '465',
+      auth: {
+        user: process.env.EMAIL_SERVER_USER,
+        pass: process.env.EMAIL_SERVER_PASSWORD,
+      },
+    })
+  }
+
+  private from() {
+    return process.env.EMAIL_FROM ?? 'Gruperly <no-reply@gruperly.com>'
+  }
+
+  private layout(title: string, body: string) {
+    return `
+      <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 480px; margin: 0 auto; padding: 24px; color: #0a2540;">
+        <h2 style="margin: 0 0 16px;">Gruperly</h2>
+        <h3 style="margin: 0 0 8px;">${title}</h3>
+        <p style="line-height: 1.6; color: #334155;">${body}</p>
+      </div>
+    `
+  }
+
+  private async send(to: string, subject: string, html: string) {
+    // Sin SMTP configurado (dev) no rompe el flujo: solo registra un aviso
+    if (!process.env.EMAIL_SERVER_HOST) {
+      console.warn(`[email] SMTP no configurado. Email no enviado a ${to}: "${subject}"`)
+      return
+    }
+    await this.transporter.sendMail({ from: this.from(), to, subject, html })
+  }
+
+  async sendVerificationEmail({ email, url, name }: VerificationEmailData) {
+    const link = `<a href="${url}" style="display:inline-block;background:#1e90ff;color:#fff;text-decoration:none;padding:12px 24px;border-radius:12px;font-weight:600;">Verificar email</a>`
+    await this.send(
+      email,
+      'Verifica tu email en Gruperly',
+      this.layout(
+        'Confirma tu dirección de email',
+        `${name ? `Hola ${name}, ` : 'Hola, '}gracias por crear tu cuenta en Gruperly. Para empezar, verifica tu email con el botón de abajo (el enlace vence en 1 hora).<br/><br/>${link}`,
+      ),
+    )
+  }
+
+  async sendPasswordResetEmail({ email, url, name }: PasswordResetEmailData) {
+    const link = `<a href="${url}" style="display:inline-block;background:#1e90ff;color:#fff;text-decoration:none;padding:12px 24px;border-radius:12px;font-weight:600;">Restablecer contraseña</a>`
+    await this.send(
+      email,
+      'Restablece tu contraseña en Gruperly',
+      this.layout(
+        'Solicitaste restablecer tu contraseña',
+        `${name ? `Hola ${name}, ` : 'Hola, '}haz clic en el botón para elegir una nueva contraseña (el enlace vence en 1 hora). Si no fuiste tú, ignora este email.<br/><br/>${link}`,
+      ),
+    )
+  }
+
+  async sendOrganizationInvitation({ email, url, organizationName }: InvitationEmailData) {
+    const link = `<a href="${url}" style="display:inline-block;background:#1e90ff;color:#fff;text-decoration:none;padding:12px 24px;border-radius:12px;font-weight:600;">Unirme a ${organizationName}</a>`
+    await this.send(
+      email,
+      `Te invitaron a ${organizationName} en Gruperly`,
+      this.layout(
+        `Te invitaron a ${organizationName}`,
+        `Acepta la invitación con el botón de abajo para empezar a colaborar en Gruperly.<br/><br/>${link}`,
+      ),
+    )
+  }
+}
+
+// Futuro: proveedores transaccionales (Resend, SendGrid, Postmark).
+// Añadir implementaciones y alternar con EMAIL_PROVIDER.
+export function createEmailProvider(): EmailProvider {
+  return new SMTPEmailProvider()
+}
+
+export const emailProvider = createEmailProvider()

apps/backend/src/lib/error-message.ts

@@ -0,0 +1,3 @@
+export function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

apps/backend/src/lib/pagination.ts

@@ -0,0 +1,25 @@
+type PaginationInput = {
+  page: number;
+  pageSize: number;
+};
+
+type PaginationMetadata = PaginationInput & {
+  total: number;
+  totalPages: number;
+};
+
+export function getPaginationMetadata(
+  { page, pageSize }: PaginationInput,
+  total: number,
+): PaginationMetadata {
+  return {
+    page,
+    pageSize,
+    total,
+    totalPages: Math.ceil(total / pageSize),
+  };
+}
+
+export function getPaginationOffset({ page, pageSize }: PaginationInput): number {
+  return (page - 1) * pageSize;
+}

apps/backend/src/lib/prisma.ts

@@ -0,0 +1,72 @@
+import 'dotenv/config';
+import { type Prisma, PrismaClient } from '@generated/prisma/client';
+import type { Result } from '@gruperly/shared';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+let prismaClient: PrismaClient | undefined;
+
+function createPrismaClient(): PrismaClient {
+  const databaseUrl = process.env.DATABASE_URL;
+  if (!databaseUrl) {
+    throw new Error('DATABASE_URL environment variable is required');
+  }
+
+  return new PrismaClient({
+    adapter: new PrismaPg({ connectionString: databaseUrl }),
+  });
+}
+
+export function getPrismaClient(): PrismaClient {
+  prismaClient ??= createPrismaClient();
+  return prismaClient;
+}
+
+const prisma = new Proxy({} as PrismaClient, {
+  get(_target, property) {
+    const client = getPrismaClient();
+    const value = Reflect.get(client, property);
+    return typeof value === 'function' ? value.bind(client) : value;
+  },
+});
+
+export default prisma;
+
+export type PrismaTransaction = Prisma.TransactionClient;
+
+export type PrismaDb = PrismaClient | PrismaTransaction;
+
+class ResultRollbackError<TError> extends Error {
+  constructor(readonly result: Result<never, TError>) {
+    super('Transaction rolled back because callback returned Result.err');
+  }
+}
+
+export class UnitOfWork {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async execute<T>(callback: (tx: PrismaTransaction) => Promise<T>): Promise<T> {
+    return this.prisma.$transaction(callback);
+  }
+
+  async executeResult<TValue, TError>(
+    callback: (tx: PrismaTransaction) => Promise<Result<TValue, TError>>,
+    options?: { isolationLevel?: Prisma.TransactionIsolationLevel },
+  ): Promise<Result<TValue, TError>> {
+    try {
+      return await this.prisma.$transaction(async (tx) => {
+        const result = await callback(tx);
+        if (!result.ok) {
+          throw new ResultRollbackError(result);
+        }
+
+        return result;
+      }, options);
+    } catch (error) {
+      if (error instanceof ResultRollbackError) {
+        return error.result;
+      }
+
+      throw error;
+    }
+  }
+}

apps/backend/src/logger.ts

@@ -0,0 +1,72 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import pino from 'pino';
+import pinoPretty from 'pino-pretty';
+
+type LoggerEnvironment = {
+  nodeEnv?: string;
+};
+
+type RequestLogContext = {
+  requestId: string;
+};
+
+const requestLogContext = new AsyncLocalStorage<RequestLogContext>();
+
+const prettyOptions = {
+  colorize: true,
+  translateTime: 'SYS:standard',
+  ignore: 'pid,hostname',
+};
+
+const getLoggerEnvironment = (): LoggerEnvironment => ({
+  nodeEnv: process.env.NODE_ENV,
+});
+
+const isDevelopmentEnvironment = (environment: LoggerEnvironment) =>
+  environment.nodeEnv !== 'production';
+
+const isTestEnvironment = (environment: LoggerEnvironment) => environment.nodeEnv === 'test';
+
+export const runWithRequestLogContext = <T>(requestId: string, callback: () => T): T =>
+  requestLogContext.run({ requestId }, callback);
+
+const getRequestLogMetadata = () => {
+  const context = requestLogContext.getStore();
+
+  if (!context) {
+    return {};
+  }
+
+  return { requestId: context.requestId };
+};
+
+export const createLoggerOptions = (environment: LoggerEnvironment): pino.LoggerOptions => ({
+  enabled: !isTestEnvironment(environment),
+  level: isDevelopmentEnvironment(environment) ? 'debug' : 'info',
+  mixin: () => getRequestLogMetadata(),
+  formatters: {
+    level(label, number) {
+      return {
+        level: number,
+        severity: label.toUpperCase(),
+      };
+    },
+  },
+});
+
+export const createLogger = (
+  environment: LoggerEnvironment = getLoggerEnvironment(),
+) => {
+  const options = createLoggerOptions(environment);
+  if (isTestEnvironment(environment)) {
+    return pino({ ...options, level: 'silent' });
+  }
+
+  if (isDevelopmentEnvironment(environment)) {
+    return pino(options, pinoPretty(prettyOptions));
+  }
+
+  return pino(options);
+};
+
+export const logger = createLogger();

apps/backend/src/modules/auth/auth.ts

@@ -0,0 +1,64 @@
+import { passkey } from '@better-auth/passkey';
+import { betterAuth } from 'better-auth';
+import { prismaAdapter } from 'better-auth/adapters/prisma';
+import { organization } from 'better-auth/plugins/organization';
+import { emailProvider } from '@/lib/email';
+import { getPrismaClient } from '@/lib/prisma';
+
+export const auth = betterAuth({
+  appName: 'Gruperly',
+  basePath: '/api/v1/auth',
+  database: prismaAdapter(getPrismaClient(), {
+    provider: 'postgresql',
+  }),
+  emailAndPassword: {
+    enabled: true,
+    minPasswordLength: 8,
+    sendResetPassword: async ({ user, url }) => {
+      await emailProvider.sendPasswordResetEmail({
+        email: user.email,
+        url,
+        name: user.name,
+      })
+    },
+  },
+  emailVerification: {
+    sendOnSignUp: true,
+    sendOnSignIn: true,
+    autoSignInAfterVerification: true,
+    sendVerificationEmail: async ({ user, token }) => {
+      const webUrl = process.env.WEB_URL ?? 'http://localhost:6173'
+      const verificationUrl = new URL('/verify-email', webUrl)
+      verificationUrl.searchParams.set('token', token)
+      await emailProvider.sendVerificationEmail({
+        email: user.email,
+        url: verificationUrl.toString(),
+        name: user.name,
+      })
+    },
+  },
+  socialProviders: {
+    ...(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET
+      ? {
+          google: {
+            clientId: process.env.GOOGLE_CLIENT_ID,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+          },
+        }
+      : {}),
+  },
+  plugins: [
+    organization({
+      acronym: 'GRP',
+      allowUserToCreateOrganization: true,
+      organizationLimit: 10,
+    }),
+    passkey({
+      rpName: 'Gruperly',
+    }),
+  ],
+  trustedOrigins: [
+    process.env.BETTER_AUTH_URL ?? 'http://localhost:4000',
+    process.env.WEB_URL ?? 'http://localhost:6173',
+  ],
+})

apps/backend/src/modules/auth/index.ts

@@ -0,0 +1 @@
+export { default as authRoutes } from './routes';

apps/backend/src/modules/auth/routes.ts

@@ -0,0 +1,8 @@
+import { Hono } from 'hono';
+import { auth } from './auth';
+
+const routes = new Hono();
+
+routes.all('*', (c) => auth.handler(c.req.raw));
+
+export default routes;

apps/backend/src/modules/groups/features/create-from-organization/route.ts

@@ -0,0 +1,27 @@
+import type { CreateGroupFromOrganization } from '@gruperly/shared';
+import { CreateGroupFromOrganizationSchema } from '@gruperly/shared';
+import { Hono } from 'hono';
+import { problemJson, unauthorizedProblem } from '@/http/problem-details';
+import { validate } from '@/http/validate';
+import { CreateGroupFromOrganization as UseCase } from './use-case';
+
+const route = new Hono();
+
+route.post('/', validate.json(CreateGroupFromOrganizationSchema), async (c) => {
+  const user = c.get('user');
+  if (!user) {
+    return problemJson(c, unauthorizedProblem(c.req.path));
+  }
+
+  const data = c.req.valid('json') as CreateGroupFromOrganization;
+  const useCase = new UseCase();
+  const result = await useCase.execute(data, user.id);
+
+  if (!result.ok) {
+    return problemJson(c, result.error);
+  }
+
+  return c.json(result.value, result.value.alreadyExists ? 200 : 201);
+});
+
+export default route;

apps/backend/src/modules/groups/features/create-from-organization/use-case.ts

@@ -0,0 +1,92 @@
+import type { Prisma } from '@generated/prisma/client';
+import { Role } from '@generated/prisma/client';
+import type {
+  CreateGroupFromOrganization as CreateGroupFromOrganizationInput,
+  CreateGroupFromOrganizationResult,
+  ProblemDetails,
+  Result,
+} from '@gruperly/shared';
+import { err, ok } from '@gruperly/shared';
+import {
+  groupOwnerRequiredProblem,
+  organizationNotFoundProblem,
+} from '@/http/problem-builders';
+import { default as prisma, UnitOfWork } from '@/lib/prisma';
+import { type GroupDb, toGroupDto } from '../../lib';
+
+type CreateGroupFromOrganizationDeps = {
+  db?: Pick<GroupDb, 'group' | 'groupMember' | 'organization'>;
+  unitOfWork?: UnitOfWork;
+};
+
+type GroupRecord = {
+  id: string;
+  name: string;
+  description: string | null;
+  createdById: string;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export class CreateGroupFromOrganization {
+  constructor(private readonly deps: CreateGroupFromOrganizationDeps = {}) {}
+
+  async execute(
+    data: CreateGroupFromOrganizationInput,
+    userId: string,
+  ): Promise<Result<CreateGroupFromOrganizationResult, ProblemDetails>> {
+    const db = this.deps.db ?? prisma;
+    const unitOfWork = this.deps.unitOfWork ?? new UnitOfWork(prisma);
+
+    const organization = await db.organization.findUnique({
+      where: { id: data.organizationId },
+      include: { members: true },
+    });
+    if (!organization) {
+      return err(organizationNotFoundProblem(data.organizationId));
+    }
+
+    const membership = organization.members.find((member: { userId: string; role: string }) => member.userId === userId);
+    if (membership?.role !== 'owner') {
+      return err(groupOwnerRequiredProblem());
+    }
+
+    const existing = await db.group.findFirst({
+      where: { createdById: userId, name: organization.name },
+    });
+    if (existing) {
+      return ok({ group: toGroupDto(existing), alreadyExists: true });
+    }
+
+    const transaction = unitOfWork.executeResult(
+      async (tx: Prisma.TransactionClient) => {
+        const created = await tx.group.create({
+          data: {
+            name: organization.name,
+            createdById: userId,
+          },
+        });
+
+        await tx.groupMember.create({
+          data: {
+            groupId: created.id,
+            userId,
+            role: Role.OWNER,
+          },
+        });
+
+        return ok(created);
+      },
+    );
+
+    const result = await transaction;
+    if (!result.ok) {
+      return result;
+    }
+
+    return ok({
+      group: toGroupDto(result.value as GroupRecord),
+      alreadyExists: false,
+    });
+  }
+}

apps/backend/src/modules/groups/features/get-all/route.ts

@@ -0,0 +1,23 @@
+import type { GroupQuery } from '@gruperly/shared';
+import { GroupQuerySchema } from '@gruperly/shared';
+import { Hono } from 'hono';
+import { problemJson, resultJson, unauthorizedProblem } from '@/http/problem-details';
+import { validate } from '@/http/validate';
+import { ListGroups } from './use-case';
+
+const route = new Hono();
+
+route.get('/', validate.query(GroupQuerySchema), async (c) => {
+  const user = c.get('user');
+  if (!user) {
+    return problemJson(c, unauthorizedProblem(c.req.path));
+  }
+
+  const query = c.req.valid('query') as GroupQuery;
+  const useCase = new ListGroups();
+  const result = await useCase.execute(query, user.id);
+
+  return resultJson(c, result);
+});
+
+export default route;

apps/backend/src/modules/groups/features/get-all/use-case.ts

@@ -0,0 +1,51 @@
+import type { Prisma } from '@generated/prisma/client';
+import type {
+  GroupList,
+  GroupQuery,
+  ProblemDetails,
+  Result,
+} from '@gruperly/shared';
+import { ok } from '@gruperly/shared';
+import { getPaginationMetadata, getPaginationOffset } from '@/lib/pagination';
+import prisma from '@/lib/prisma';
+import { buildGroupWhereForUser, type GroupDb, toGroupDto } from '../../lib';
+
+type ListGroupsDeps = {
+  db?: Pick<GroupDb, 'group'>;
+};
+
+type GroupRecord = {
+  id: string;
+  name: string;
+  description: string | null;
+  createdById: string;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export class ListGroups {
+  constructor(private readonly deps: ListGroupsDeps = {}) {}
+
+  async execute(
+    query: GroupQuery,
+    userId: string,
+  ): Promise<Result<GroupList, ProblemDetails>> {
+    const db = this.deps.db ?? prisma;
+    const where = buildGroupWhereForUser(userId) as Prisma.GroupWhereInput;
+
+    const [records, total] = await Promise.all([
+      db.group.findMany({
+        where,
+        skip: getPaginationOffset(query),
+        take: query.pageSize,
+        orderBy: { createdAt: 'desc' },
+      }),
+      db.group.count({ where }),
+    ]);
+
+    return ok({
+      data: records.map((record: GroupRecord) => toGroupDto(record)),
+      pagination: getPaginationMetadata(query, total),
+    });
+  }
+}

apps/backend/src/modules/groups/index.ts

@@ -0,0 +1 @@
+export { default as groupsRoutes } from './routes';

apps/backend/src/modules/groups/lib/helpers.ts

@@ -0,0 +1,33 @@
+import type { PrismaClient } from '@generated/prisma/client';
+import type { GroupDto } from '@gruperly/shared';
+
+export type GroupDb = Pick<PrismaClient, 'group' | 'groupMember' | 'organization'>;
+
+type GroupRecord = {
+  id: string;
+  name: string;
+  description: string | null;
+  createdById: string;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export function toGroupDto(record: GroupRecord): GroupDto {
+  return {
+    id: record.id,
+    name: record.name,
+    description: record.description,
+    createdById: record.createdById,
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt.toISOString(),
+  };
+}
+
+export function buildGroupWhereForUser(userId: string) {
+  return {
+    OR: [
+      { createdById: userId },
+      { members: { some: { userId } } },
+    ],
+  };
+}

apps/backend/src/modules/groups/lib/index.ts

@@ -0,0 +1 @@
+export * from './helpers';

apps/backend/src/modules/groups/routes.ts

@@ -0,0 +1,10 @@
+import { Hono } from 'hono';
+import createFromOrganizationRoute from './features/create-from-organization/route';
+import getAllRoute from './features/get-all/route';
+
+const routes = new Hono();
+
+routes.route('/', getAllRoute);
+routes.route('/from-organization', createFromOrganizationRoute);
+
+export default routes;

apps/backend/src/modules/health-check/features/get-health-check/route.ts

@@ -0,0 +1,14 @@
+import { Hono } from 'hono';
+import { resultJson } from '@/http/problem-details';
+import { GetHealthCheck } from './use-case';
+
+const route = new Hono();
+
+route.get('/', async (c) => {
+  const useCase = new GetHealthCheck({ instance: c.req.path });
+  const result = await useCase.execute();
+
+  return resultJson(c, result);
+});
+
+export default route;

apps/backend/src/modules/health-check/features/get-health-check/use-case.ts

@@ -0,0 +1,35 @@
+import type { PrismaClient } from '@generated/prisma/client';
+import type { HealthCheck, ProblemDetails, Result } from '@gruperly/shared';
+import { err, ok } from '@gruperly/shared';
+import { databaseUnavailableProblem } from '@/http/problem-builders';
+import prisma from '@/lib/prisma';
+import { logger } from '@/logger';
+
+type GetHealthCheckDeps = {
+  db?: PrismaClient;
+  instance: string;
+};
+
+export class GetHealthCheck {
+  constructor(private readonly deps: GetHealthCheckDeps) {}
+
+  async execute(): Promise<Result<HealthCheck, ProblemDetails>> {
+    const { instance } = this.deps;
+    const db = this.deps.db ?? prisma;
+
+    try {
+      await db.$queryRaw`SELECT 1`;
+    } catch (error) {
+      logger.warn({ error, instance }, 'Database health check failed');
+      return err(databaseUnavailableProblem({ instance }));
+    }
+
+    return ok({
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+      checks: {
+        database: 'ok',
+      },
+    });
+  }
+}

apps/backend/src/modules/health-check/index.ts

@@ -0,0 +1 @@
+export { default as healthCheckRoutes } from './routes';

apps/backend/src/modules/health-check/routes.ts

@@ -0,0 +1,8 @@
+import { Hono } from 'hono';
+import getHealthCheckRoute from './features/get-health-check/route';
+
+const routes = new Hono();
+
+routes.route('/', getHealthCheckRoute);
+
+export default routes;

apps/backend/src/modules/payments/features/get-all/route.ts

@@ -0,0 +1,18 @@
+import type { PaymentQuery } from '@gruperly/shared';
+import { PaymentQuerySchema } from '@gruperly/shared';
+import { Hono } from 'hono';
+import { resultJson } from '@/http/problem-details';
+import { validate } from '@/http/validate';
+import { ListPayments } from './use-case';
+
+const route = new Hono();
+
+route.get('/', validate.query(PaymentQuerySchema), async (c) => {
+  const query = c.req.valid('query') as PaymentQuery;
+  const useCase = new ListPayments();
+  const result = await useCase.execute(query);
+
+  return resultJson(c, result);
+});
+
+export default route;

apps/backend/src/modules/payments/features/get-all/use-case.ts

@@ -0,0 +1,58 @@
+import type { PrismaClient } from '@generated/prisma/client';
+import type { PaymentDto, PaymentList, PaymentQuery, ProblemDetails, Result } from '@gruperly/shared';
+import { ok } from '@gruperly/shared';
+import { getPaginationMetadata, getPaginationOffset } from '@/lib/pagination';
+import prisma from '@/lib/prisma';
+
+type ListPaymentsDeps = {
+  db?: Pick<PrismaClient, 'payment'>;
+};
+
+type PaymentRecord = {
+  id: string;
+  groupId: string;
+  studentId: string;
+  amount: { toString(): string };
+  currency: string;
+  status: PaymentDto['status'];
+  dueDate: Date;
+  paidAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+function toPaymentDto(record: PaymentRecord): PaymentDto {
+  return {
+    id: record.id,
+    groupId: record.groupId,
+    studentId: record.studentId,
+    amount: Number(record.amount.toString()),
+    currency: record.currency,
+    status: record.status,
+    dueDate: record.dueDate.toISOString(),
+    paidAt: record.paidAt ? record.paidAt.toISOString() : null,
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt.toISOString(),
+  };
+}
+
+export class ListPayments {
+  constructor(private readonly deps: ListPaymentsDeps = {}) {}
+
+  async execute(query: PaymentQuery): Promise<Result<PaymentList, ProblemDetails>> {
+    const db = this.deps.db ?? prisma;
+    const [records, total] = await Promise.all([
+      db.payment.findMany({
+        skip: getPaginationOffset(query),
+        take: query.pageSize,
+        orderBy: { createdAt: 'desc' },
+      }),
+      db.payment.count(),
+    ]);
+
+    return ok({
+      data: records.map(toPaymentDto),
+      pagination: getPaginationMetadata(query, total),
+    });
+  }
+}

apps/backend/src/modules/payments/index.ts

@@ -0,0 +1 @@
+export { default as paymentsRoutes } from './routes';

apps/backend/src/modules/payments/routes.ts

@@ -0,0 +1,8 @@
+import { Hono } from 'hono';
+import getAllRoute from './features/get-all/route';
+
+const routes = new Hono();
+
+routes.route('/', getAllRoute);
+
+export default routes;

apps/backend/src/modules/students/features/get-all/route.ts

@@ -0,0 +1,18 @@
+import type { StudentQuery } from '@gruperly/shared';
+import { StudentQuerySchema } from '@gruperly/shared';
+import { Hono } from 'hono';
+import { resultJson } from '@/http/problem-details';
+import { validate } from '@/http/validate';
+import { ListStudents } from './use-case';
+
+const route = new Hono();
+
+route.get('/', validate.query(StudentQuerySchema), async (c) => {
+  const query = c.req.valid('query') as StudentQuery;
+  const useCase = new ListStudents();
+  const result: Awaited<ReturnType<typeof useCase.execute>> = await useCase.execute(query);
+
+  return resultJson(c, result);
+});
+
+export default route;

apps/backend/src/modules/students/features/get-all/use-case.ts

@@ -0,0 +1,58 @@
+import type { PrismaClient } from '@generated/prisma/client';
+import type { ProblemDetails, Result, StudentDto, StudentList, StudentQuery } from '@gruperly/shared';
+import { ok } from '@gruperly/shared';
+import { getPaginationMetadata, getPaginationOffset } from '@/lib/pagination';
+import prisma from '@/lib/prisma';
+
+type ListStudentsDeps = {
+  db?: Pick<PrismaClient, 'student'>;
+};
+
+type StudentRecord = {
+  id: string;
+  groupId: string;
+  fullName: string;
+  email: string | null;
+  phone: string | null;
+  guardianName: string | null;
+  guardianPhone: string | null;
+  notes: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+function toStudentDto(record: StudentRecord): StudentDto {
+  return {
+    id: record.id,
+    groupId: record.groupId,
+    fullName: record.fullName,
+    email: record.email,
+    phone: record.phone,
+    guardianName: record.guardianName,
+    guardianPhone: record.guardianPhone,
+    notes: record.notes,
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt.toISOString(),
+  };
+}
+
+export class ListStudents {
+  constructor(private readonly deps: ListStudentsDeps = {}) {}
+
+  async execute(query: StudentQuery): Promise<Result<StudentList, ProblemDetails>> {
+    const db = this.deps.db ?? prisma;
+    const [records, total] = await Promise.all([
+      db.student.findMany({
+        skip: getPaginationOffset(query),
+        take: query.pageSize,
+        orderBy: { createdAt: 'desc' },
+      }),
+      db.student.count(),
+    ]);
+
+    return ok({
+      data: records.map(toStudentDto),
+      pagination: getPaginationMetadata(query, total),
+    });
+  }
+}

apps/backend/src/modules/students/index.ts

@@ -0,0 +1 @@
+export { default as studentsRoutes } from './routes';

apps/backend/src/modules/students/routes.ts

@@ -0,0 +1,8 @@
+import { Hono } from 'hono';
+import getAllRoute from './features/get-all/route';
+
+const routes = new Hono();
+
+routes.route('/', getAllRoute);
+
+export default routes;

apps/backend/src/modules/waitlist/features/get-all/route.ts

@@ -0,0 +1,18 @@
+import type { WaitlistQuery } from '@gruperly/shared';
+import { WaitlistQuerySchema } from '@gruperly/shared';
+import { Hono } from 'hono';
+import { resultJson } from '@/http/problem-details';
+import { validate } from '@/http/validate';
+import { ListWaitlistEntries } from './use-case';
+
+const route = new Hono();
+
+route.get('/', validate.query(WaitlistQuerySchema), async (c) => {
+  const query = c.req.valid('query') as WaitlistQuery;
+  const useCase = new ListWaitlistEntries();
+  const result = await useCase.execute(query);
+
+  return resultJson(c, result);
+});
+
+export default route;

apps/backend/src/modules/waitlist/features/get-all/use-case.ts

@@ -0,0 +1,50 @@
+import type { PrismaClient } from '@generated/prisma/client';
+import type { ProblemDetails, Result, WaitlistEntryDto, WaitlistList, WaitlistQuery } from '@gruperly/shared';
+import { ok } from '@gruperly/shared';
+import { getPaginationMetadata, getPaginationOffset } from '@/lib/pagination';
+import prisma from '@/lib/prisma';
+
+type ListWaitlistEntriesDeps = {
+  db?: Pick<PrismaClient, 'waitlistEntry'>;
+};
+
+type WaitlistRecord = {
+  id: string;
+  email: string;
+  name: string | null;
+  status: WaitlistEntryDto['status'];
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+function toWaitlistEntryDto(record: WaitlistRecord): WaitlistEntryDto {
+  return {
+    id: record.id,
+    email: record.email,
+    name: record.name,
+    status: record.status,
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt.toISOString(),
+  };
+}
+
+export class ListWaitlistEntries {
+  constructor(private readonly deps: ListWaitlistEntriesDeps = {}) {}
+
+  async execute(query: WaitlistQuery): Promise<Result<WaitlistList, ProblemDetails>> {
+    const db = this.deps.db ?? prisma;
+    const [records, total] = await Promise.all([
+      db.waitlistEntry.findMany({
+        skip: getPaginationOffset(query),
+        take: query.pageSize,
+        orderBy: { createdAt: 'desc' },
+      }),
+      db.waitlistEntry.count(),
+    ]);
+
+    return ok({
+      data: records.map(toWaitlistEntryDto),
+      pagination: getPaginationMetadata(query, total),
+    });
+  }
+}

apps/backend/src/modules/waitlist/index.ts

@@ -0,0 +1 @@
+export { default as waitlistRoutes } from './routes';

apps/backend/src/modules/waitlist/routes.ts

@@ -0,0 +1,8 @@
+import { Hono } from 'hono';
+import getAllRoute from './features/get-all/route';
+
+const routes = new Hono();
+
+routes.route('/', getAllRoute);
+
+export default routes;

apps/backend/src/server.ts

@@ -0,0 +1,36 @@
+import 'dotenv/config';
+import { serve } from '@hono/node-server';
+import app from '@/app';
+import { getPrismaClient } from '@/lib/prisma';
+import { logger } from '@/logger';
+
+const port = Number(process.env.PORT ?? 4000);
+
+logger.info(`Server running on http://localhost:${port}`);
+
+const server = serve({
+  fetch: app.fetch,
+  port,
+});
+
+async function shutdown(): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      resolve();
+    });
+  });
+  await getPrismaClient().$disconnect();
+}
+
+process.once('SIGINT', () => {
+  void shutdown();
+});
+
+process.once('SIGTERM', () => {
+  void shutdown();
+});