**Language:** [English](README.md) | [Русский](README.ru.md) | [Deutsch](README.de.md) | [Español](README.es.md)

# EUSRR

EUSRR is an internal enterprise portal for employees, requests, documents,
procurement, scheduling, attendance and realtime communications. The current
application consists of a Django/DRF ASGI backend and a Next.js frontend.

## Current capabilities

- employee directory, departments, positions, permissions and optional LDAP/AD synchronization;
- requests, approval workflows, tasks and notification-driven status changes;
- documents, attachments, comments and acknowledgements;
- procurement requests, approval routes, budgets and equipment inventory;
- calendars, shared events and attendance analysis through LogStorm;
- chats, reactions, polls and user notifications over one authenticated WebSocket connection;
- notification delivery through WebSocket, email and Web Push.

## Stack

- Backend: Python 3.13, Django 5.2, Django REST Framework, Channels and Daphne.
- Data and jobs: PostgreSQL, Redis, Celery and Celery Beat.
- Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS, TanStack Table and Recharts.
- Integrations: LDAP/Active Directory, Web Push and LogStorm.
- Tests: pytest/pytest-django, Node test runner, ESLint and Next.js production build.

Pinned dependency versions are defined in [`backend/requirements.txt`](backend/requirements.txt)
and [`frontend/package.json`](frontend/package.json).

## Documentation and runtime contracts

- [Documentation index](docs/README.md)
- [HTTP API](docs/guides/API.md)
- [LDAP and Active Directory](docs/guides/LDAP.md)
- [WebSocket and realtime](docs/guides/WEBSOCKET.md)
- [Notifications](docs/guides/NOTIFICATIONS.md)
- [Commerce and MoySklad](docs/guides/COMMERCE.md)

With the backend running, generated contracts are available at:

- `http://localhost:8000/api/docs/` — Swagger UI;
- `http://localhost:8000/api/redoc/` — ReDoc;
- `http://localhost:8000/api/schema/` — OpenAPI;
- `http://localhost:8000/api/ws/docs/` — WebSocket documentation;
- `http://localhost:8000/api/ws/schema/` — AsyncAPI.

## Repository layout

```text
backend/   Django apps, REST API, Celery tasks, migrations and backend tests
frontend/  Next.js application and frontend tests
docs/      Maintained API, integration, operations and development guides
```

## Local development

Prerequisites: Python 3.13, Node.js 20 or newer, PostgreSQL and Redis. The
`backend/docker-compose.yml` file only creates a development Samba AD environment;
it is not a full application stack.

Create the root environment file:

```bash
cp .env.example .env
```

The example uses service hostnames `db` and `redis`. For services running on the
local machine, change `DB_HOST` and `REDIS_HOST` to `127.0.0.1`, set
`DEBUG=True`, and provide an existing PostgreSQL database and credentials. LDAP
is disabled in the example and is not required for local login.

Backend:

```bash
cd backend
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python manage.py migrate
daphne -b 0.0.0.0 -p 8000 eusrr_backend.asgi:application
```

Run Celery when testing asynchronous notifications, digests, LDAP retries or
other background jobs:

```bash
cd backend
celery -A eusrr_backend worker -l info
celery -A eusrr_backend beat -l info
```

Frontend:

```bash
cd frontend
cp .env.example .env.local
npm install
npm run dev
```

Open `http://localhost:3000`. Browser HTTP requests are proxied by Next.js to
`NEXT_PUBLIC_BACKEND_URL`; realtime uses the backend `/ws/` endpoint.

## Verification

```bash
cd backend
pytest
python manage.py check
```

```bash
cd frontend
npm test
npm run lint
npm run build
```

Use focused test suites while developing. A full run may require PostgreSQL,
Redis or explicitly mocked integrations depending on the selected tests.

## Security and data

Environment files, local databases, uploaded media, certificates, generated
builds and dependency directories are ignored by Git. Never commit production
data or secrets.

Some legacy settings still have development fallback values for LDAP and VAPID.
Do not rely on them outside an isolated development environment: override all
credentials through environment variables and rotate any key that has ever been
stored in source control. Example values are placeholders, not production
configuration.

The repository is not a source of production data. Review company-specific
domains, branding and directory DNs before using it in another environment.