# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

IDIS v2 is a Node.js/Express web application that integrates with the Turkish IDIS (portal.idis.gov.tr) API. It uses MongoDB (via Mongoose), EJS templating with Tailwind CSS, and vanilla JavaScript on the client side. The entire codebase (UI, variables, comments) is in Turkish.

## Commands

- `npm run dev` — Start dev server with nodemon (auto-reload on changes)
- `npm start` — Start production server (`node app.js`)
- No test, lint, or build commands are configured

## Architecture

**MVC pattern with a service layer:**

- `app.js` — Entry point. Configures Express, sessions, middleware chain, static files, and routes
- `config/db.js` — MongoDB connection setup
- `models/` — Mongoose schemas (User, Setting, UserActivity, ErrorLog, ExceptionPlate, TransitHistory)
- `controllers/` — Request handlers, one per feature area
- `services/` — Business logic and external integrations (IDIS API login, session lifecycle, email, background processing)
- `routes/` — Express route definitions, one per feature area
- `views/` — EJS templates with `layout.ejs` as the main layout; `partials/` for reusable snippets
- `js/` — Client-side JavaScript (served as static files), one per page
- `css/style.css` — Minimal custom styles (Tailwind via CDN handles most styling)

**Middleware chain order (defined in app.js):**
1. IP whitelist check — auto-login from whitelisted IPs (stored in Settings model)
2. Express-session with MongoDB store (connect-mongo, 365-day TTL)
3. `requireAuth` — protects HTML page routes; API routes bypass this
4. Activity logging — records page visits for authenticated users

**Session management:**
- Single-device login enforced: each User stores `activeSessionId`, `activeSessionIP`, `activeSessionUA`, `activeSessionAt`
- `sessionManager.js` manages multiple session types with different lifetimes (app: 3hrs, web: 1hr)
- Admin can force-logout users

**Key services:**
- `autoTransitProcessor.js` — Background automated tag query processing
- `appLoginService.js` / `webLoginService.js` — IDIS API authentication
- `habasMailService.js` / `idcMailService.js` — Email integrations
- `captchaService.js` — Captcha handling for external portal

**Data retention:** UserActivity and ErrorLog models use MongoDB TTL indexes for automatic 90-day cleanup.

## Environment

Requires a `.env` file with: `PORT`, `MONGODB_URI`, `IDIS_API_BASE_URL`, `IDIS_CLIENT_ID`, `IDIS_CLIENT_SECRET`, `SESSION_SECRET`. Runs on Node.js v24 (has a DNS workaround for Cloudflare compatibility).
