Project

Contributing

Contributions are welcome. Before you start, read the Roadmap page — the known gaps and priorities are there.

Getting started

git clone https://github.com/mahmutyum/ticket-system.git
cd ticket-system
cp .env.example .env         # değerleri doldur — bkz. docs/kurulum.md
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
docker compose exec backend npx tsx prisma/seed.ts

Details and troubleshooting: Installation.

For a technical overview of the codebase: Architecture.

Before submitting a change

CI (.github/workflows/ci.yml) runs all of these on PRs, but passing them locally saves time:

# Backend
cd backend
npm run typecheck         # source type check
npm run typecheck:tests   # test files (separate tsconfig — main build rootDir:src)
npm run lint
npm test
 
# Frontend
cd ../frontend
npm run typecheck
npm run lint
npm run build

CI also applies the migrations to a real Postgres and verifies that the schema matches the database — if you change the schema and forget to generate a migration, it gets caught there.

Coding conventions

The backend is ESM. In relative imports the .js extension is mandatory — even when the source file is .ts: import { foo } from './foo.js'. If you forget, it blows up at runtime; tsc won't catch it.
All input is validated with Zod.
API response: { success: boolean, data?: T, error?: string }.
Bilingual (TR/EN). User-facing text is not hardcoded: frontend react-i18next (i18n/locales + per-page i18n/pages), backend API messages i18n/messages/* + t(request, key) (Accept-Language). tr = original, en = translation.
Status/priority/role constants live in backend/src/config/constants.ts — don't scatter string literals.
Call createAuditLog() on admin/staff CRUD operations.
Frontend: one component per file, data fetching with TanStack Query.
Follow the style of the existing code. There is no lint/format tool yet; consistency is maintained by hand.

Database changes

If you change the schema, generate a migration and include it in the commit:

docker compose exec backend npx prisma migrate dev --name aciklayici_bir_ad

Read the generated SQL. If you open a migration that drops a column or table, note it in the PR description.

Don't use prisma db push. It skips the migration history. The project has deliberately moved to versioned migrations.

Security-sensitive areas

If you touch these files, take extra care and give a rationale in the PR description:

Area	Why
`plugins/auth.ts`, `utils/staff-scope.ts`	Auth and company scope. Tested (`tests/utils/staff-scope`, `tests/routes/management-scope`) but with a high risk of silent regression — review the tests too when you change them.
`modules/tickets/public.routes.ts`	The unauthenticated surface. Internal notes must never leak from here.
`utils/crypto.ts`, `modules/credentials/`	The credential vault. Changing the encryption format makes existing records unreadable.
`modules/notes/`	The `isInternal` filter.

If you find a security vulnerability, don't open an issue — follow the path in the Security page.

For what may and may not enter the repo (secrets, real data, PII, production screenshots) and the pre-commit check: docs/public-repo.md.

Commit and PR

Make commit messages descriptive. The feat(scope): ..., fix(scope): ... form is preferred. Turkish or English, either is fine.
The Co-Authored-By line is not used.
In the PR description: what changed, why, how you tested it. If there is a schema change or a behavior change, state it explicitly.
Small, focused PRs move faster.

Where to start

Relatively independent work items from the roadmap:

The "My Tickets" view — the requester's email-verified, unified ticket list (the flow is described in the roadmap). A new public page + a short-lived verification flow.
Expand test coverage — especially scope/RBAC and public-surface scenarios; existing examples are under tests/routes/.
Accessibility and UX — expand the Playwright/axe scenarios.

Roadmap