dinmukhamad/puls

Purpose and Entry Points

Puls is an internal call-center operator motivation/gamification platform: roles, KPI ratings, coin economy, rewards, learning missions, and operational reporting. FastAPI serves both the JSON API and the vanilla-JS SPA.

• app/main.py

• app/api/router.py

• index.html

Application Composition

app/main.py assembles the application: configuration, middleware, lifespan startup/shutdown work, API router, health/readiness endpoints, and static SPA delivery. Domain routers are centrally mounted once rather than independently exposed.

• app/core/config.py

• app/core/lifespan.py

• app/core/static.py

Security and Request Boundary

Authentication is JWT-backed HttpOnly cookie auth. Middleware enforces CORS, compression, and CSRF/origin protections; authorization is implemented at domain API boundaries for operator, supervisor, manager, and admin scopes. Production startup rejects unsafe configuration.

• app/modules/auth/router.py

• app/core/security.py

• app/core/middleware.py

Persistence, Schema, and Startup

PostgreSQL is the production system of record, accessed through the database layer and shared ORM entities. Alembic owns schema evolution; startup can verify schema/readiness and seed initial/admin/economy data. Local tests use temporary SQLite, but production requires PostgreSQL/psycopg.

• app/database/db.py

• app/models/entities.py

• migrations/env.py

• app/services/database_readiness.py

Reporting-to-Analytics Pipeline

Period-report uploads are parsed, validated, persisted, and used as the durable basis for ratings and analytics rather than transient JSON data. Analytics repositories/calculators produce KPI summaries, operator tables, group comparisons, and cached results; ratings add nomination and ranking logic.

• app/modules/reports/service.py

• app/modules/reports/excel_parser.py

• app/modules/analytics/service.py

• app/modules/rating/service.py

Engagement and Economy Domains

The core gamification flow connects operators and groups to levels/achievements, coin balances and transactions, seasonal shop purchases, raffles, Wheel of WOW eligibility/spins, notifications, and weekly accruals. These modules expose APIs while service layers contain transaction and rule orchestration.

• app/modules/wallet/service.py

• app/modules/economy/service.py

• app/modules/wheel/service.py

• app/modules/weekly_results/accrual_service.py

• app/modules/missions/service.py

Frontend and Delivery

The client is an HTML/CSS/vanilla-JS SPA served by FastAPI. Editable source fragments are concatenated in numeric filename order into committed browser bundles; API domain wrappers call the backend and view modules render major workflows.

• js/src/app/00-core-shell.js

• js/src/api/client/00-client-auth.js

• js/app.js

• css/styles.css

• scripts/build-frontend.mjs

Runtime and Deployment

Python 3.13/FastAPI runs under Uvicorn. Deployment targets Railway and can use Docker/Compose plus Nginx; start.sh applies Alembic migrations before serving. Required external infrastructure is PostgreSQL; no Node backend is used.

• start.sh

• Dockerfile

• deploy/docker-compose.yml

• railway.toml