NexviTechHRMS

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

AGENTS

Overview

• Monorepo contains the FinTech-inspired HRMS experience: frontend lives in apps/Frontend/HRM-Frontend (Vite + React) and the backend is the Flask service under apps/backend.
• Frontend uses Fast Refresh via Vite 7 and a JS stack focused on React Components + Redux, while the backend is Flask 3.x + SQLAlchemy + Marshmallow-style helpers.
• This AGENTS.md is the canonical playbook for agentic coding tools; keep it descriptive yet concise so automations can follow commands without extra guidance.

Environment Setup & Entry Points

• Backend prefers Python 3.11+ semantics; create a virtual env next to apps/backend with py -m venv .venv then ./ source into it depending on shell.
• Activate the backend env before any Python commands (PowerShell: . .venv/Scripts/Activate.ps1; cmd: .venv\\Scripts\\activate; bash/git-bash: source .venv/Scripts/activate).
• Install Python deps from the backend directory with pip install -r requirements.txt.
• Frontend relies on Yarn 4.10.2 despite the package-lock.json; prefer Yarn for consistency (yarn install in apps/Frontend/HRM-Frontend).
• Keep both the backend .venv and frontend node_modules directories untracked (they are already present but should not be committed again).
• When switching contexts, run backend commands from apps/backend and frontend commands from apps/Frontend/HRM-Frontend to avoid npm/node path issues.

Build / Dev Commands

• Backend dev server: flask --app hrms_api --debug run (set FLASK_APP=hrms_api via env, optionally override DATABASE_URL).
• Backend production entry (mirrors Procfile): gunicorn "hrms_api.wsgi:app" --bind 0.0.0.0:8000 --workers 2 --timeout 120 (use 1 worker when slotting into Heroku-like hosts).
• Frontend dev server: yarn dev --host from apps/Frontend/HRM-Frontend (Vite will watch files and serve assets).
• Frontend build: yarn build; use yarn preview to validate the production bundle.
• When running both locally, start the backend first so the frontend can successfully reach http://localhost:5000/api/* (or the configured API domain).

Linting & Testing

• Frontend linting: yarn lint uses ESLint (see eslint.config.js); fix autofixable issues before committing.
• Backend linting: no formal lint tool yet—consider python -m py_compile or ruff/black additions if needed and document them here.
• Backend tests: run python -m pytest tests from apps/backend.
• There are no frontend automated tests yet; rely on manual QA in Vite dev mode and incremental storybook-style verification.
• Running a single backend test (important for fast feedback): python -m pytest tests/test_pay_cycle_resolution.py::test_cycle_resolution_matches_and_priority (prefix with apps/backend/ if running from repo root).
• You can also scope tests with -k (e.g., python -m pytest tests -k compliance) or target other files such as tests/test_compliance_scope.py.
• Capture stack traces and re-run failing tests locally before pushing changes.

Imports & Module Layout

• Backend modules follow the Flask blueprint hierarchy under hrms_api/blueprints; keep imports inside create_app where they would otherwise create circular references.
• Avoid wildcard imports everywhere; group imports by standard library, third-party, and local modules with blank lines between.
• Frontend components use ES modules (import { useState } from "react"); default exports should match the filename (PascalCase).
• Use from __future__ import annotations in backend modules that reference forward-declared types (messaging blueprint already demonstrates this).
• Keep trailing commas in multi-line argument lists to minimize diff churn when adding parameters.
• Share helpers through dedicated common modules rather than duplicating logic (e.g., hrms_api/common/errors and src/services).

Formatting & Style

• Backend follows PEP 8 (79-character soft limit, 4 spaces indentation, blank lines around class/function definitions) and uses single quotes unless the string contains apostrophes.
• Frontend prefers double quotes for JSX and JSON fragments (because of ESLint config); keep the choice consistent within a file.
• Always leave a newline at the end of files, use parentheses for wrapped lines, and align chained calls vertically.
• Keep inline styles to computed scenarios; move static CSS to src/App.css or index.css and reuse CSS variables when a new palette is introduced.
• Reveal component structure; if a React file grows beyond ~200 lines, split it into smaller pieces (like the existing dashboard components).
• Use meaningful labels when interpolating (e.g., <Button label={`${status} summary`} />) and prefer const for function expressions and useMemo for expensive derivations.
• Run yarn lint after eslint --fix to ensure no new warnings.

Types & Data Modeling

• Backend relies on type hints for functions returning SQLAlchemy models; keep model relationships explicit (db.relationship) and annotate column defaults.
• When defining DTOs, consider TypedDict or dataclasses to document contract shapes; keep schemas near validation logic (see features/masters/*/schema.ts).
• Frontend constants (states, statuses) live in shared files like tradeConstants.js; import them rather than retyping the strings.
• For API payloads, document expected keys next to the axios calls (e.g., in Api.jsx or services/*Service).
• Treat backend JSON helpers as explicit (return dict with known keys) so frontend clients are not surprised by missing fields.

Naming Conventions

• Backend functions are snake_case, classes are PascalCase, blueprints follow bp naming, and constants are SCREAMING_SNAKE.
• Blueprint registration should stay grouped by domain (masters, payroll, attendance) inside create_app for readability.
• Frontend component filenames and default exports use PascalCase (EmployeeList.jsx).
• Hooks and utilities are camelCase verbs (usePayCycleApi).
• CSS class names stay kebab-case in stylesheets; prefix long-page-specific classes to avoid conflicts.
• Redux action constants remain UPPER_SNAKE and are declared next to the matching reducers.
• API helpers (e.g., fetchDesignations, createDesignation) are named after the resource and action.

Error Handling & Logging

• All Flask errors funnel through hrms_api.common.errors; raise APIError for business issues and let the handlers convert them to fail payloads.
• Only catch exceptions when you can recover; for everything else, allow the global handler (which logs with app.logger.exception) to process them.
• CLI commands use click.echo rather than print so output can be siphoned by automation.
• Avoid returning raw tracebacks in HTTP responses; always wrap failure messages with the fail helper and include safe details in logs.
• Frontend axios calls should be wrapped in try/catch with toast feedback (the Messaging page already follows this pattern).
• External integrations (Rocket.Chat requests) always specify timeout and swallow RequestException to keep endpoints resilient.
• Document retries and fallbacks with inline comments (similar to _generate_rc_token).

Testing & QA Notes

• Backend tests under tests/ use in-memory SQLite (DATABASE_URL=sqlite:///:memory:) and rely on the factory create_app.
• Each test block stays inside with app.app_context(): and calls db.create_all(); resetting the database manually is discouraged because fixtures already handle cleanup.
• To add fixtures, enlarge the test helper module (create tests/conftest.py if not present) and use db.session.flush() after bulk inserts.
• Use pytest --maxfail=1 --disable-warnings when you want quick feedback, and add -vv for verbose output when debugging.
• Frontend automated testing is absent; replicate UI flows locally by running yarn dev and exercising landing, payroll, attendance, and messaging flows.
• Note any manual QA steps in this file when they become necessary (e.g., verifying Rocket.Chat integration requires live RC server).

Frontend UI & UX Expectations

• The frontend should avoid bland layouts; choose expressive typography beyond default stacks and define CSS variables for palettes.
• Backgrounds should use gradients, subtle geometric textures, or layered color fills rather than a single flat color.
• Introduce purposeful motion (framer-motion) for page travelers or notifications, but keep it restrained and functional.
• Each page should feel distinct (e.g., Admin dashboard vs landing page) and respect spacing/shear cues already present in Components/dashboard.
• Ensure responsive behavior across breakpoints; test in Vite’s dev server with responsive mode turned on.
• When adding new colors or icons, align them with the @mui/material theme overrides already in place, and document any palette changes in index.css.

Backend Operations & Maintenance

• CLI seeders live in create_app: flask seed-core, seed-masters, seed-demo-range, seed-rgs, seed-rgs-compliance, plus targeted commands like seed-leave-types.
• Secrets such as JWT_SECRET_KEY, DATABASE_URL, and RC_* should be injected via environment variables before running the backend locally or in CI.
• Database migrations use Alembic; after altering models run flask db revision --autogenerate -m "describe change" followed by flask db upgrade.
• Reports write to reports_storage relative to the backend root; ensure this folder exists and is writable before running report-related scripts.
• One-off scripts (e.g., sync_users.py, restore_collection.py) execute against the same environment as the app; activate the same .venv to keep dependencies consistent.

Git & Collaboration Notes

• The repository root is not managed by git here, so place AGENTS.md near the workspace root to help future git initializations.
• Keep Python and JavaScript layers separated: backend files stay under apps/backend, frontend files under apps/Frontend/HRM-Frontend.
• Coordinate API changes by updating both backend blueprints and the frontend Api.jsx/service modules; mention related files in PR descriptions.
• Document major schema or API updates near the affected files and in Swstik-HRMS-DOcs so downstream dependents understand migrations.

Cursor / Copilot Rules

• No .cursor or .cursorrules directory was found in this workspace, so there are no Cursor-specific instructions to apply.
• No .github/copilot-instructions.md file exists, so Copilot keeps default behavior; update AGENTS.md if that changes.

API Client & HTTP

• Backend endpoints are grouped under /api/v1 (master_* blueprints, payroll, messaging, etc.); mirror those paths inside frontend API helpers to avoid drift.
• Centralize API configuration inside src/Api.jsx (or src/services/*Service.js), setting up base URLs, headers, and JWT cookies.
• When adding new blueprints, keep registration in create_app grouped by domain (health, auth, master, payroll) and register error blueprints last.
• Document API contracts (params, payloads) near the handler so frontend devs know what to expect; use inline comments where the schema changes.
• Keep documentation synced with Swstik-HRMS-DOcs when a new public endpoint or API version is introduced.

Shared Utilities & Hooks

• Feature hooks (like features/masters/grades/hooks.ts) stay close to their feature folder and follow useSomething naming.
• Avoid repeating API fetch logic; wrap axios calls with shared helpers that include consistent error handling and toasts.
• Backend common modules (errors.py, http.py) should stay small; prefer importing fail/ok to keep blueprints thin.
• CLI seeders and helpers output progress via click.echo so log scrapers or humans know what executed; don’t mix print statements with click.
• When adding a new CLI command, describe it with a short docstring and mention required environment variables inside the function body.

Data Validation & Schema

• Backend validation happens via marshmallow or manual checks; validate enums before writing to the database and raise APIError on failure.
• SQLAlchemy models should declare __repr__ for debugging but never include sensitive attributes.
• JSON response helpers should drop None values when they are not meaningful; keep frontal DTOs clean.
• Frontend forms rely on schema files (schema.ts under each feature); update those schemas when enabling/disabling fields.
• Share dropdown options and constants via modules to avoid literal duplication (see payCycleConstants.js).

Observability & Debugging

• Logs mostly use app.logger; include relevant IDs (company_id, user_id, request ID) so traces can be correlated.
• Debug endpoints such as /api/v1/messaging/debug exist for local verification; keep them disabled or guarded in production.
• Frontend debugging should rely on structured console.debug calls with descriptive prefixes; remove noisy logs before shipping.
• When calling Rocket.Chat APIs, log the HTTP response code and payload on failures to ease triage.
• Pytest can be run with --capture=no to see print output if you rely on temporary prints during debugging.

Documentation & Knowledge Base

• Keep this AGENTS.md current whenever you add new build/test commands or style rules.
• For domain-heavy modules (pay cycles, compliance, messaging), annotate the directory with short READMEs or inline comments explaining the flow.
• Refer to Swstik-HRMS-DOcs for formal documentation; update it when onboarding new teams or documenting long-running modules.
• Questions? Update this file or ask the maintainers so future agents do not guess the workflow.
• Treat this document as the source of truth for agentic automation; add future hints or command updates here.