How vishwak27/workforcely works
Purpose and Entry Points
Workforcely is a Django 5 internal administration system for managing employees and departments. It exposes two interfaces over shared domain logic: a server-rendered HTMX UI rooted at /, and DRF REST endpoints with Swagger documentation at /api/schema/swagger-ui/. Process entry points are manage.py, plus deployment adapters at config/wsgi.py and config/asgi.py.
Django Project Composition
The project configuration and global routing boundary live in config/settings.py and config/urls.py. These define installed applications, middleware, database/environment integration, API/UI route inclusion, and schema/documentation exposure. config/asgi.py and config/wsgi.py support ASGI and WSGI hosting runtimes.
Department Domain
The departments app owns department persistence, API representation, and use cases. departments/models.py defines the database entity; departments/services.py centralizes department queries, validation, mutations, and aggregate logic; departments/serializers.py adapts model data for DRF. Both API and rendered interfaces enter through departments/views.py, with app-local routing in departments/urls.py.
Employee Domain
The employees app similarly owns employee records and employee-specific query behavior. Its architectural distinction is filtering, isolated in employees/filters.py, while service-level read/write and validation flows reside in employees/services.py. HTTP adapters are employees/views.py and employees/urls.py; API payload boundaries are defined by employees/serializers.py; persistence is in employees/models.py.
Shared Service-Layer Flow
Views should remain transport adapters: DRF ViewSets and HTMX-oriented views delegate business operations to the corresponding services.py module rather than directly duplicating ORM logic. The primary flow is request → URL/view adapter → domain service → Django ORM/model → database, followed by either serialized JSON for API clients or rendered HTML/partial HTML for browser clients. This keeps filtering, validation, and aggregate counts consistent across delivery channels.
Server-Rendered HTMX UI
The frontend app provides the dashboard and page-level UI routes through frontend/views.py and frontend/urls.py. Templates establish full-page and fragment response boundaries: templates/base.html is the shell, templates/dashboard.html is the landing dashboard, and _stats_partial.html supports independently refreshed statistics. Department and employee list/form/table fragments under templates/departments/ and templates/employees/ are intended for HTMX swaps, driven without a JavaScript build runtime.
Data, Dependencies, and Operations
Django migrations in departments/migrations/0001_initial.py and employees/migrations/0001_initial.py establish the relational schema. seed_data.json supplies bootstrap records via Django’s fixture loader. Material dependencies are Django, Django REST Framework, HTMX (browser-side), Tailwind CSS styling, and OpenAPI/Swagger UI; exact package versions and supporting libraries are governed by requirements.txt. Environment-backed deployment settings are expected via .env, modeled by .env.example.
Components 19
Project boundary
- Django entry points · CLI, WSGI, and ASGI process entry points.
manage.py - Settings
config/settings.py - Root routing & docs · Includes UI and API routes and exposes Swagger UI.
config/urls.py
Departments domain
- Department HTTP adapters · DRF and rendered request adapters.
departments/urls.py - Department services · Centralizes queries, validation, mutations, and aggregates.
departments/services.py - Department serializers
departments/serializers.py - Department model
departments/models.py
Employees domain
- Employee HTTP adapters · DRF and rendered request adapters.
employees/urls.py - Employee services · Owns employee reads, writes, and validation.
employees/services.py - Employee filters · Isolates employee query filtering behavior.
employees/filters.py - Employee serializers
employees/serializers.py - Employee model
employees/models.py
Rendered UI
- Dashboard routes & views
frontend/urls.py - Page templates · Base shell and dashboard page.
templates/base.html - Statistics partial · Independently refreshed dashboard statistics.
- Domain HTMX fragments · Department and employee list, form, and table swaps.
Other components
- Relational database · Schema is established by the domain migrations.
- API clients · Use DRF endpoints and Swagger documentation.
- Browser with HTMX · Receives full pages and swapped fragments.
Connections 20
- Django entry points → Settings: boots with
- Settings → Root routing & docs: configures
- Root routing & docs → Department HTTP adapters: includes
- Root routing & docs → Employee HTTP adapters: includes
- Root routing & docs → Dashboard routes & views: includes
- API clients → Root routing & docs: REST requests
- Browser with HTMX → Root routing & docs: page and HTMX requests
- Department HTTP adapters → Department services: delegates to
- Department HTTP adapters → Department serializers: serializes API responses
- Department services → Department model: queries and mutates
- Employee HTTP adapters → Employee services: delegates to
- Employee HTTP adapters → Employee serializers: serializes API responses
- Employee services → Employee filters: applies
- Employee services → Employee model: queries and mutates
- Department model → Relational database: persists to
- Employee model → Relational database: persists to
- Dashboard routes & views → Page templates: renders
- Dashboard routes & views → Statistics partial: returns
- Department HTTP adapters → Domain HTMX fragments: renders
- Employee HTTP adapters → Domain HTMX fragments: renders