The projects module in src/cluster_erp/modules/projects/ manages customer projects. A project (Project) is opened when a sales order's PO is received and follows a fixed lifecycle. It carries items to produce, fixtures to make, a versioned schedule with activities, a kick-off meeting, weekly meetings, and actions. A read-only board and calendar show all projects with their production reality. This page is the overview; the sub-topics have their own pages.
At a glance¶
| Item | Value | Source |
|---|---|---|
| Package | src/cluster_erp/modules/projects/ |
folder |
| Module class | Module |
src/cluster_erp/modules/projects/module.py:18 |
name / version |
projects / 0.1.0 |
src/cluster_erp/modules/projects/module.py:20-25 |
| API prefix | /api/v1/projects (ModuleBase.api_prefix) |
src/cluster_erp/core/module_base.py:37-38 |
| Sub-modules | 8: projects, items, fixtures, schedules, activities, kickoffs, meetings, actions; plus board.py and board_routes.py |
folder listing |
| Tables | 10 | __tablename__ in the eight models.py files |
| Entities in metadata | 8 keys in entities |
src/cluster_erp/modules/projects/module.py:323-332 |
| Routes | 64 route decorators in the package | grep for @...router.get/post/put/patch/delete |
| Actions | 8 ActionMeta entries |
grep "ActionMeta(" in the package |
| Migrations | 14 files | files in migrations/versions/ whose text contains one of the ten table names |
| Web app presence | Catalogue app projects; custom widgets project_board, project_calendar, and the home widgets home_board and home_calendar from a gated bundle |
src/cluster_erp/modules/app_store/catalog.json (entry projects), gated_apps/projects/app.js:1035 |
| Desktop presence | generic widgets only | src/cluster_erp/desktop/modules/ has no projects folder |
What the module does¶
- Opens one project per sales order when the order's PO is received (
src/cluster_erp/modules/projects/module.py:95-130). - Moves a project along a fixed lifecycle from
planningtoclosed(src/cluster_erp/modules/projects/projects/services.py:32-43). - Keeps project items with a product breakdown and creates production orders for them (
src/cluster_erp/modules/projects/items/models.py:17-80,src/cluster_erp/modules/projects/items/routes.py:88-138). - Keeps fixture requirements, schedules with activities and relations, kick-offs, weekly meetings, and actions (
src/cluster_erp/modules/projects/module.py:66-75). - Reads production roll-up and hour-based earned value from the
productionmodule (src/cluster_erp/modules/projects/projects/routes.py:102-268). - Serves the board and calendar read model (
src/cluster_erp/modules/projects/board.py:1-11).
Sub-modules¶
| Sub-module | Purpose | Main entities | Router | Source |
|---|---|---|---|---|
projects |
Projects, lifecycle, roll-up, EVM | Project |
/projects |
src/cluster_erp/modules/projects/projects/routes.py:28 |
items |
What the project delivers | ProjectItem |
/project-items |
src/cluster_erp/modules/projects/items/routes.py:22 |
fixtures |
Fixtures, jigs, tools, equipment to make | FixtureRequirement |
/fixtures |
src/cluster_erp/modules/projects/fixtures/routes.py:21 |
schedules |
Versioned project schedules | ProjectSchedule |
/schedules |
src/cluster_erp/modules/projects/schedules/routes.py:19 |
activities |
Schedule activities, relations, material links | ProjectActivity, ProjectActivityRelation, ActivityMaterialLink |
/activities |
src/cluster_erp/modules/projects/activities/routes.py:24 |
kickoffs |
Kick-off meeting and checklist | KickoffMeeting |
/kickoffs |
src/cluster_erp/modules/projects/kickoffs/routes.py:20 |
meetings |
Weekly follow-up meetings | WeeklyFollowupMeeting |
/meetings |
src/cluster_erp/modules/projects/meetings/routes.py:20 |
actions |
Actions from meetings or ad hoc | ProjectAction |
/actions |
src/cluster_erp/modules/projects/actions/routes.py:22 |
| board | Board and calendar read model | none | /project-board |
src/cluster_erp/modules/projects/board_routes.py:17 |
All routers are mounted under the module prefix with require_app("projects") (src/cluster_erp/modules/projects/module.py:66-76).
Data model¶
Fields are listed on projects and items, actions, activities, and meetings, and schedules. Project items carry product_id, product_model_id, and product_version_id (src/cluster_erp/modules/projects/items/models.py:42-53). A project's stock_mode is common or project_striped, which decides whether its stock is kept in a project stripe of the inventory module (src/cluster_erp/modules/projects/projects/schemas.py:13). Fixture cost estimates are Numeric (src/cluster_erp/modules/projects/fixtures/models.py:47).
Screens and metadata¶
get_metadata declares a sidebar group Projects (Turkish Projeler) with the list Projects and the custom sections Board and Calendar (src/cluster_erp/modules/projects/module.py:288-320). It also declares two home widgets, Project Board and Project Calendar (src/cluster_erp/modules/projects/module.py:266-283). The board is explained on project board; home widgets on home widgets.
Status and actions¶
Status changes go through the action Change Status (transition) on projects, fixtures, and actions; schedules have Publish and Share with Customer; kick-offs have Mark as Held and Update Checklist; items have Create Production Order (src/cluster_erp/modules/projects/projects/metadata.py:55-64, src/cluster_erp/modules/projects/schedules/metadata.py:82-101, src/cluster_erp/modules/projects/kickoffs/metadata.py:43-62, src/cluster_erp/modules/projects/items/metadata.py:115-127). Status machines are on the sub-topic pages.
Business rules¶
Each sub-topic page lists its rules. Business keys come from the yearly sequences project, project_item, and fixture_requirement (src/cluster_erp/modules/projects/projects/services.py:124, src/cluster_erp/modules/projects/items/services.py:59, src/cluster_erp/modules/projects/fixtures/services.py:60).
Events and queries¶
The module consumes 4 contracts and produces 17, counted as on the parties module page. The full list is on the contracts reference.
| Direction | Contract class | Handler or emitter | Source |
|---|---|---|---|
| emits | ProjectCreated, ProjectStatusChanged, ProjectKickoffCompleted, ProjectClosed |
ProjectService |
src/cluster_erp/modules/projects/projects/services.py:142-290 |
| emits | ProjectSchedulePublished, ProjectScheduleShared, ProjectActivityChanged, ProjectActionCreated, ProjectFixtureRequired |
sub-module services | src/cluster_erp/modules/projects/schedules/services.py:139-170, src/cluster_erp/modules/projects/activities/services.py:50, src/cluster_erp/modules/projects/actions/services.py:94, src/cluster_erp/modules/projects/fixtures/services.py:77, src/cluster_erp/modules/projects/kickoffs/services.py:114 |
| queries | GetSalesOrderById, GetProjectProductionRollup, GetProjectProductionEvm, GetProjectSalesDelivery, GetProjectProductionSchedule, GetOwnerWorkingDays, GetPartyForEmployee, CreateProductionOrderForProject |
services and routes | src/cluster_erp/modules/projects/board.py:162-201, src/cluster_erp/modules/projects/board_routes.py:36-44 |
| answers query | GetProjectById, IsKickoffCompleted, GetProjectMemberPartyIds |
handlers in module.py |
src/cluster_erp/modules/projects/module.py:89-93 |
| subscribes | SalesOrderPoReceived |
_on_sales_order_po_received |
src/cluster_erp/modules/projects/module.py:95 |
Permissions¶
| Permission key | Used by | Source |
|---|---|---|
project.read, .create, .update, .delete, .bulk_delete |
project routes and the reads of all sub-modules | src/cluster_erp/modules/projects/projects/routes.py:40-310 |
project.update |
changes to items, fixtures, schedules, activities | src/cluster_erp/modules/projects/items/routes.py:37-139, src/cluster_erp/modules/projects/activities/routes.py:105-192 |
action.assign |
create an action and change its status | src/cluster_erp/modules/projects/actions/routes.py:49, src/cluster_erp/modules/projects/actions/routes.py:88 |
meeting.record |
kick-off and meeting changes | src/cluster_erp/modules/projects/kickoffs/routes.py:37-101, src/cluster_erp/modules/projects/meetings/routes.py:35-85 |
CreateProductionOrderForProject.REQUIRED_PERMISSION |
item production order | src/cluster_erp/modules/projects/items/routes.py:88-100 |
Privacy, retention, and history¶
The module has no privacy_handlers.py. Deletes set deleted_at, including kick-offs and meetings (src/cluster_erp/modules/projects/kickoffs/services.py:122-125, src/cluster_erp/modules/projects/meetings/services.py:79-82). Changes are captured by change history.
Analytics facts¶
This module has no analytics_facts.py.
Settings and reference data¶
The module has no settings section. The board's default horizon is 7 days back and 56 days ahead, as module constants (src/cluster_erp/modules/projects/board.py:43-45).
Tests¶
Found by a grep for modules.projects in tests/ and for the path /projects/ in web-client/_e2e_*.mjs.
| Kind | File | Covers |
|---|---|---|
| pytest | tests/test_tenant_field_catalog.py |
tenant fields on projects |
| e2e | web-client/_e2e_project_board.mjs, web-client/_e2e_project_calendar.mjs |
the board and calendar |
| e2e | web-client/_e2e_project_key_phase0.mjs, web-client/_e2e_project_plan_phase1.mjs |
project key and production plan |
| e2e | web-client/_e2e_project_stock_phase2a.mjs, web-client/_e2e_project_pegging_phase2b.mjs, web-client/_e2e_project_evm_phase2c.mjs |
project stock, pegging, and EVM |
| e2e | web-client/_e2e_project_otd.mjs, web-client/_e2e_widget_projects.mjs, web-client/_e2e_widget_scope.mjs |
on-time delivery and the home widgets |
Terms introduced¶
| Term | Code identifier | Definition | Turkish term | Source |
|---|---|---|---|---|
| project | Project |
A customer project opened from a sales order, with a fixed lifecycle. | Proje | src/cluster_erp/modules/projects/projects/models.py:22 |
| stock mode | stock_mode |
Whether a project uses common stock or its own stock stripe. | Stok modu | src/cluster_erp/modules/projects/projects/schemas.py:13 |
Related pages¶
- Modules index
- Projects and items
- Actions, activities, and meetings
- Schedules
- Project board
- Production module
- API reference for this module
Verified against commit 92f8051 on 2026-11-13.