Commercial Subsystem Design
===========================

1. Purpose
----------

Build a semi-autonomous commercial front inside the digital twin to operate:

- prospecting
- contact
- supplier registration
- commercial follow-up
- ALEPH CRM updates
- daily agenda
- executive daily brief

This phase precedes further twin development.

2. Business Objective
---------------------

Convert dispersed information into a disciplined, repeatable commercial operation.

The system must:

- identify relevant prospects (national & international)
- classify by segment and product
- consolidate buying signals
- prepare and sustain contact
- manage supplier registration
- use ALEPH as operational memory
- generate daily actionable agenda
- generate executive daily report

3. Design Principles
--------------------

3.1 Separate national and international flows

- different requirements
- different markets
- different regulations
- different channels

3.2 ALEPH as system of record

The twin suggests; ALEPH records:

- contacts
- activities
- follow-ups

3.3 Action over analysis

Outputs must include:

- next contacts
- overdue tasks
- registrations pending
- reactivation opportunities

3.4 Rules before models

Start with deterministic logic.

4. Scope
--------

Included:

- commercial model
- national/international flows
- prospect structure
- enrichment
- ALEPH integration
- agenda
- daily brief

Excluded (for now):

- aggressive LinkedIn automation
- large-scale scraping
- predictive scoring

5. Architecture
---------------

External Sources
    → Prospecting
    → Enrichment
    → Classification
    → Prioritization
    → ALEPH Sync
    → Daily Agenda
    → Daily Brief

6. Main Flows
-------------

6.1 National Flow

Stages:

1. company discovery
2. segmentation
3. product fit
4. contact identification
5. procurement evaluation
6. supplier registration
7. ALEPH registration
8. follow-up

6.2 International Flow

Stages:

1. market selection
2. account targeting
3. fit evaluation
4. supplier registration tracking
5. buyer identification
6. CRM registration
7. follow-up

7. Core Entity: Prospect
------------------------

Definition:

A commercial opportunity in evolution.

Structure:

- prospect_id
- market_type (national/international)
- country
- company_name
- segment
- target_products
- product_fit_score
- financial_signal
- procurement_signal
- vendor_registration_status
- crm_status
- next_action
- priority_score

8. Related Entities
-------------------

prospect_contact

- contact_id
- role
- email

prospect_activity

- activity_type
- date
- outcome

prospect_requirement

- requirement
- status

prospect_signal

- signal_type
- source

9. Prospect States
------------------

- NEW
- QUALIFYING
- RESEARCHING
- CONTACT_READY
- CONTACTED
- FOLLOW_UP
- VENDOR_REGISTRATION
- ACTIVE_OPPORTUNITY
- DORMANT
- LOST
- WON

10. Segmentation
----------------

segment_product_map:

- segment
- product
- rules

11. Enrichment Blocks
---------------------

- commercial
- financial
- procurement
- digital signals

12. LinkedIn Use
----------------

- research
- content suggestion
- monitoring

13. ALEPH Integration
---------------------

Sync:

- contacts
- activities
- follow-ups

14. Daily Agenda
----------------

Sections:

- today
- overdue
- reactivation
- registrations
- priorities

15. Daily Brief
---------------

Content:

- actions performed
- new prospects
- priorities
- decisions required

16. Prioritization
------------------

Based on:

- product fit
- strategic value
- activity

17. Metrics
-----------

- prospects per week
- contacts
- follow-ups

18. Modules
-----------

prodisys/commercial/

- prospect_model.py
- prospect_store.py
- prospect_ingest.py
- crm_sync.py
- agenda.py
- daily_brief.py

19. Implementation Order
------------------------

1. model
2. store
3. ingest
4. CRM sync
5. agenda

20. Success Criteria
--------------------

- structured prospect pipeline
- daily agenda
- ALEPH integration
- executive brief

21. Next Step
-------------

Implement prospect_model.py