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

AGENTS.md — Mentor Engineering & Agent Guide

Canonical guide. CLAUDE.md and other agent tools point here. Single source of product decisions: sinav-kocluk-roadmap.md (Turkish). Design system: DESIGN.md. Architecture detail: docs/.

0. Product spirit (the compass for every decision)

This is a "companionship platform" — not a knowledge platform. On the long, lonely, exhausting road of exam prep, it's an AI coach + community that understands, keeps you going, and never leaves you alone. The deepest pain isn't lack of information; it's loneliness, collapse of motivation, giving up. For every feature, ask: does it soothe that pain?

Exam-agnostic product: the AI-coach / ritual / social / analysis logic is the same across all exams (KPSS/YKS/LGS). Exams differ only by content/config (taxonomy, net rule, calendar source). Do not write a separate "vertical". KPSS = first seed.
Tone: Turkish, encouraging, never shaming. Countdown is calm (not alarm-red), no result ranking, no "bottom of the leaderboard". Canonical copy constitution: docs/copy/voice.md (dual register Puhu/Companion, sen address, no em dash —, no AI slop, no "lütfen", non-monetary hak).

1. Architecture line (locked — §8)

Single language: TypeScript. Single API (/v1, versioned, backward-compatible).
Backend: NestJS modular monolith. Clear module boundaries; extract to services later if needed.
Web/Admin: Next.js (App Router). Mobile: Expo (Phase 2).
i18n: apps/web is TR/EN (URL-based, next-intl; tr default). All FE static copy via useTranslations/getTranslations, internal nav via @/i18n/navigation, keys mirrored in messages/{tr,en}.json — details in docs/standards/frontend.md §i18n + docs/features/i18n.md.
Monorepo: Turborepo + pnpm. apps/* + packages/*.
DB: Neon Postgres + pgvector · ORM: Drizzle. RLS on the Postgres side.
Queue: behind JobQueuePort — MVP Cron+jobs table, Phase 2 BullMQ+Redis (rationale: docs/core/architecture.md).
DB driver: single pg Pool (drizzle-orm/node-postgres) — works local + Neon; tx-scoped RLS via withUserContext / SET LOCAL (§8).
Edge: Cloudflare (WAF/RateLimit/Turnstile/R2/Images/Access). Hosting: Render.
AI: OpenAI (text, GPT-5) + Gemini Flash (vision) + rule engine (hybrid) + pgvector RAG.
Auth: own JWT (refresh rotation, argon2). Payments: iyzico. Email: Postmark. Monitoring: Sentry.

2. Module map (bounded contexts — §8)

identity · coaching · ai · content · payments · notifications · admin   (MVP)
economy · forum · community · mentorship                               (Phase 2)
marketplace                                                            (Phase 3)

Rule: modules never touch each other's tables → public interface or domain event (NestJS EventEmitter; moves to a queue if modules split out). Detail: apps/api/src/modules/README.md.

3. Patterns (§8)

Repository+DI · Ports & Adapters (shared/ports) · Domain Events (loose coupling) · append-only Ledger (XP/coin, never delete) · Idempotency (webhook/jobs) · Outbox (economy/payments) · Strategy (AI routing/rewards/ verification) · Policy/Guard + RLS (tenancy). Full table + where: docs/core/architecture.md, backend.md.

Pragmatic Clean: layer depth scales with the work. Simple CRUD → controller+service+repo. Critical domain (economy/payments/ai/forum-verification) → full layering.

4. Absolute guardrails (do not violate)

Official information (dates/process/placement) is never free-generated by the LLM and is never left to community/coach approval — it always comes from verified editorial content (§1). Critical facts (dates) → data card render (no paraphrase → no hallucination).
Photo→topic only CATEGORIZES, never solves (§0/§10). Vision = classification.
Economy: coin is non-monetary, capped. Never put coin in the chat zone. The ledger never stores a single number / never deletes. Reward ≤ action value (don't leak AI cost — §3).
No unconditional/ongoing AI on Free (cost ~0). The three ways to taste AI: carded trial · earned right (invite/quest) · a curated coach's sponsored seat, bounded by mentorship.coach.free_seats. No unconditional metered sampling (§7/§10). The seat was added 2026-09-05 (APP-076) and revises roadmap §7's "koçtan abonelik sıkma". It is a widening, not a removal: the path is conditional on a coach account in good standing, on a config'd seat count, and on mentorship.seats.sponsorship_enabled, and every call it funds still sits under ai.budget.monthly_cap_usd_cents. free_seats is the single knob that bounds the whole exposure — coaches x seats = giveaway premium. Raise it deliberately. REVISED 2026-09-08 (APP-089): "manually curated COACH role" is no longer what bounds the coach count. Registration is self-service, so the number of coaches is bounded by the number of verified email addresses somebody can produce — which is not a bound. The seat exposure is therefore gated on the SEQUENCE, not on curation: mentorship.seats.sponsorship_enabled must not be switched on before SMS OTP ships. Until then sponsorship_enabled = false is the whole defence, and it is off. See the flag runbook in docs/features/mentorship.md.
AI→teacher trust line: a student's raw confessions to the AI never reach the teacher/coach — only signals/flags (§9). This is the foundation of AI-companion trust (§0).
KVKK: PII-free summary to the LLM; no-training API; foreign-transfer disclosure. Behavioral data in Postgres (RLS); pgvector is content only, not behavioral data (§8).
Data model is org_id/coach-ready from day one (even if unused in MVP) → Phase 2/3 won't break (§10).

5. Avoid over-engineering (§8)

❌ In MVP: full CQRS+Event Sourcing, microservices, 4-layer ceremony in every module, Redis, K8s.
✅ Now: clear module boundaries + repository + DI + domain events + ledger + idempotency + ports.
Rule: add a pattern only once you feel the pain it solves. For now, just draw the boundaries right.

6. Monorepo & commands

pnpm install                          # root — entire workspace
pnpm dev                              # turbo: all apps (api:3001 web:3000 admin:3002)
pnpm --filter @mentor/api dev         # single app
pnpm build | lint | typecheck         # turbo pipeline
pnpm --filter @mentor/api db:generate # generate Drizzle migration

Packages: @mentor/{types,validation,core,api-client,ui,config}. Path alias @mentor/*. Structure detail: docs/core/file-structure.md.

Iterative verification scope (binding)

After each scoped development step, do not run workspace-wide full test, lint, typecheck, or build by default. Run the smallest relevant test suites plus targeted checks for the touched files/packages.
Expand verification only when a targeted failure indicates wider impact, the change affects a high-risk or cross-cutting surface (auth, payments, migrations, shared contracts), the user explicitly requests it, or the branch is being declared PR/merge/release-ready.
Full CI remains mandatory before merge/release. Never claim the whole workspace is green from targeted checks.

7. Conventions

Language: code/identifiers in English; user-facing text in Turkish (Turkish product); comments and engineering docs in English. Exceptions (intentionally Turkish): README.md (product/user-facing overview) and sinav-kocluk-roadmap.md (product decision record).
Validation: Zod is the single source (@mentor/validation), shared FE+BE.
Types: shared contracts in @mentor/types. Avoid any.
Commits: Conventional Commits (feat:, fix:, chore:, docs:, refactor:).
Branches: main protected; work on feat/<topic>, merge via PR.
Design: UI values come from DESIGN.md tokens (@mentor/ui), no magic numbers.
Config: tunable parameters in a central registry (§9) — not magic numbers.
Modularity: keep files manageable (<250–300 lines target). Decompose proactively during development (FE: subcomponents, view stages, params helpers; BE: sub-services, domain calculators, strategies, query helpers, DTO mappers; thin controllers).
Full list: docs/core/conventions.md.

8. Skill usage (when developing in this repo)

senior-architect → module boundaries, event design, tech decisions, diagrams.
senior-backend → NestJS modules/endpoints, Drizzle schema/queries, auth, payments, queue.
senior-frontend → Next.js pages/components, state, applying DESIGN.md. Read apps/web/AGENTS.md or apps/admin/AGENTS.md depending on which app you're in (admin has accepted stack deviations).
code-reviewer → PR checklist, guardrails §4, merge readiness (code-review.md).
vercel-react-best-practices → performance constitution for all React/Next.js code (priority: async-waterfall → bundle → server → client → re-render). New FE code follows it.
ui-ux-pro-max / frontend-design → screen design (stay faithful to DESIGN.md tokens).
expo / building-native-ui / expo-tailwind-setup → Phase 2 mobile (RN), port @mentor/ui tokens to RN.
Invoke the relevant skill per task; ground decisions in the roadmap and this file.

Mobile (critical): do NOT use Expo Router API routes — single API = NestJS /v1 (a second backend breaks it). expo-api-routes is for EAS hosting/deploy only; all data comes from NestJS via @mentor/api-client.

9. Phase discipline & parallel work

Parallel development: MVP work is split into tracks with exclusive ownership — read docs/core/workstreams.md before picking up work. Don't write inside another track's module; shared files are append-only per its touch rules.
MVP: responsive web B2C + lean admin. Social/forum/economy/coach/mobile = Phase 2+.
A feature's phase is set by roadmap §10. Don't do out-of-scope work "by the way" — push it to backlog.

10. Standards & documentation (binding)

Standards & documentation (binding): docs/standards/ · Copy constitution: docs/copy/voice.md.
Engineering principles: docs/standards/engineering-principles.md — SOLID/DRY/KISS/YAGNI, modularity & size discipline (<250–300 lines FE+BE; proactive decomposition during development), no hardcoding/silent fallbacks, edge cases vs over-defensiveness, logic backend-only, backend-localized messages, Definition of Done (incl. dead-code cleanup)
Code style & naming: docs/standards/code-style.md — file/class/variable/DB/event names, format, imports, git
API design & versioning + service catalog: docs/standards/api.md
Backend: docs/standards/backend.md
Frontend: docs/standards/frontend.md
Mobile: docs/standards/mobile.md
Code review: docs/standards/code-review.md

Feature-doc rule (mandatory): After every meaningful development, append a short/clear/explanatory entry to the matching feature doc under docs/features/ ("Geliştirmeler (timeline)" section): what was done · how to use (usage) · gotchas · related files. A meaningful PR without a feature-doc entry is not merged. Full doc index: docs/README.md.

MentorApp

About