How yenchenliu/workforce works
Project Type and Purpose
• This is a Django-based, RESTful workforce scheduling application (monolithic backend API).
• Its core responsibility is to expose an “assign-tasks” endpoint that uses linear programming to produce optimal worker-task assignments and return KPI data.
File Structure
Top-level directories/files:
• .github/workflows/ci.yml – CI pipeline definition
• manage.py – Django CLI entry point
• requirements.txt / requirements.in – Python dependencies
• mypy.ini – static-type check config
• seed_data/…json – initial data for positions, tasks, workers, assignments
• workforce/ – Django project settings, ASGI/WGI and URL routing
• assignments/ – Django app containing models, services, API, schemas, migrations, tests, and a custom management command
README for Additional Insights
• Confirms Python 3.12+, Django 5.0+
• Describes CLI commands (migrate, load_seed_data, runserver)
• Mentions built-in API docs at /api/docs
• Highlights the assign-tasks linear-programming service
a. Client Layer
• Web or API client (e.g. browser calling /api/docs, third-party scheduler clients)
b. API/Web Layer
• ASGI/WGSI server (e.g. Daphne or Gunicorn)
• Django URL router (workforce/urls.py)
• DRF (or Django generic views) endpoints in assignments/api.py
c. Business-Logic Layer
• Service module (assignments/services.py) implementing the linear programming solver
• Schemas or serializers (assignments/schemas.py) for input/output validation
d. Data-Access Layer
• Django ORM models (assignments/models.py)
• Migrations for schema evolution (assignments/migrations/…)
e. Persistence
• Relational database (PostgreSQL, MySQL, or SQLite in dev)
f. Initialization & DevOps
• Management command (load_seed_data) to populate seed_data/*.json into the database
• CI pipeline (.github/workflows/ci.yml) running tests and type checks
g. External Libraries/Services
• Linear-programming library (PuLP, OR-Tools or similar, listed in requirements.txt)
• Third-party dependencies (Django, DRF, database driver)
Relationships and Data Flows
• Client → HTTP → ASGI/WGSI server
• Server → URL router → View/API endpoint
• View → Schemas/Serializers (validate request)
• View → Services (invoke LP solver, business rules)
• Services → ORM (read/write assignments, tasks, worker capacities)
• ORM → Database (CRUD operations)
• Service returns results → Serializer → HTTP Response → Client
Architectural Patterns and Design Principles
• Layered architecture (Presentation → API → Services → Data Access → Persistence)
• Single-responsibility modules: separate modules for API, business logic, data models, schemas
• Use of Django’s management-command pattern for one-off tasks (seed data)
• Configuration-as-code (settings.py, CI YAML)
• Type safety and static analysis (mypy.ini)
• Test-driven development (assignments/tests.py + codecov integration)
2. Next row: Load balancer (optional) → ASGI Server (Gunicorn/Daphne)
3. Middle: Django core layers—URL router → API view → serializer → services → ORM
4. Bottom: Database, LP library
5. Side: Management commands and CI workflow