Imported from yunusemreerkesikbas/MentorApp (
AGENTS.md). Install upstream withnpx skills add yunusemreerkesikbas/MentorApp. Copyright stays with the author.
AGENTS.md — Mentor Engineering & Agent Guide
Canonical guide.
CLAUDE.mdand 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/webis TR/EN (URL-based, next-intl;trdefault). All FE static copy viauseTranslations/getTranslations, internal nav via@/i18n/navigation, keys mirrored inmessages/{tr,en}.json— details indocs/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
pgPool (drizzle-orm/node-postgres) — works local + Neon; tx-scoped RLS viawithUserContext/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 onmentorship.seats.sponsorship_enabled, and every call it funds still sits underai.budget.monthly_cap_usd_cents.free_seatsis 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_enabledmust not be switched on before SMS OTP ships. Until thensponsorship_enabled = falseis the whole defence, and it is off. See the flag runbook indocs/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) andsinav-kocluk-roadmap.md(product decision record). - Validation: Zod is the single source (
@mentor/validation), shared FE+BE. - Types: shared contracts in
@mentor/types. Avoidany. - Commits: Conventional Commits (
feat:,fix:,chore:,docs:,refactor:). - Branches:
mainprotected; work onfeat/<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.mdorapps/admin/AGENTS.mddepending 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/uitokens 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.mdbefore 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.
