# Canadian Federal Election Game Simulator Plan

## Purpose

Build a Canadian federal election game simulator with two major surfaces:

1. A frontend where the player can inspect Canada by riding, click ridings on a map, search/list ridings, view local political values, and make campaign decisions.
2. A backend simulation engine that generates a future federal campaign, advances one day at a time, runs party and leader activities, updates polls, models riding-level opinion, and produces election results.

The game should focus only on Canadian federal politics. Provincial politics can exist as background flavour only when it affects federal riding culture, regional identity, or issue salience.

## Technical Stack

The first implementation should be built as a Laravel 9 application using PHP 8.1.2 and SQLite.

Stack assumptions:

- PHP 8.1.2.
- Laravel 9.
- SQLite for local development and first playable builds.
- Blade for server-rendered pages unless a later frontend pass needs a heavier JavaScript layer.
- Laravel migrations and seeders for all generated election data.
- Laravel services for simulation logic.
- Eloquent models for persisted campaign state.
- Simple JSON API endpoints where the map and live election-night UI need partial refreshes.
- Local GeoJSON/TopoJSON files for riding map geometry once the map phase begins.

SQLite design notes:

- Use integer ids and indexed foreign keys.
- Keep large map geometry outside high-write simulation tables.
- Store daily snapshots as compact rows rather than huge JSON blobs when charts need to query them often.
- JSON columns can be used for flexible debug payloads, action metadata, and calculation breakdowns, but core game state should be queryable.
- Avoid database-specific SQL that would make a future MySQL/PostgreSQL move painful.

## Current Political Baseline

This baseline should be treated as seed data, not hard-coded truth. The app should support replacing leaders, parties, ridings, and polls from admin pages or seed files.

Canada currently uses 343 federal electoral districts after the 2022 redistribution. A majority government requires 172 seats. The simulator should model each district as a first-past-the-post contest where the top local candidate wins the seat.

Core federal parties to support in the first playable version:

- Liberal Party of Canada
- Conservative Party of Canada
- New Democratic Party
- Bloc Quebecois
- Green Party of Canada
- People's Party of Canada
- Independents and optional minor registered parties

Initial real-world leader seed set as of May 2026:

- Liberal: Mark Carney
- Conservative: Pierre Poilievre
- NDP: Avi Lewis
- Bloc Quebecois: Yves-Francois Blanchet
- Green: Elizabeth May
- People's Party: Maxime Bernier

Reference sources to re-check before building production seeders:

- Elections Canada federal electoral districts: https://www.elections.ca/content.aspx?dir=cir&document=index&lang=E&section=res
- Elections Canada registered parties: https://www.elections.ca/content.aspx?dir=par&document=index&lang=e&section=pol
- House of Commons composition reference: https://www.ourcommons.ca/procedure-and-practice-4/ch04-2-e.html
- Party websites for leader data and public positioning.

## Core Game Loop

The campaign is generated with an election date in the future. Each turn represents one campaign day.

Daily loop:

1. Start day snapshot.
2. Generate national and regional news context.
3. Let the player choose leader actions, campaign travel, speeches, advertising, policy announcements, debate prep, fundraising, local candidate boosts, or damage control.
4. Run AI decisions for non-player parties.
5. Resolve events, speeches, scandals, endorsements, economic updates, and media cycles.
6. Update leader popularity, party brand, issue ownership, enthusiasm, turnout, fundraising, organization, and riding-level preferences.
7. Update national, regional, demographic, and riding polls.
8. Produce daily reports, maps, alerts, and poll movement.
9. Advance toward election day.
10. On election day, simulate turnout, local vote shares, winners, seat totals, popular vote, government type, and post-election summaries.

## Player Roles

The first version should let the player control one party as campaign director.

Later versions can add:

- Prime minister mode for incumbents.
- Opposition leader mode.
- War room mode with multiple staff roles.
- Sandbox observer mode.
- Custom fictional party mode.
- Multiplayer hot-seat mode.

## Campaign Calendar

Campaigns should support:

- Pre-writ period.
- Writ drop.
- Official campaign.
- Debate nights.
- Advance polling days.
- Final weekend.
- Election day.

Suggested default campaign lengths:

- Short campaign: 36 days.
- Standard campaign: 45 days.
- Long campaign: 60 days.
- Sandbox: 90 to 365 days.

Important campaign date fields:

- `campaign_start_date`
- `writ_date`
- `election_date`
- `current_date`
- `days_remaining`
- `phase`
- `turn_number`

## Riding Model

Every riding needs its own political fingerprint. The simulator should not simply apply national swing evenly. National movement should be filtered through local values, demographics, incumbency, candidates, history, and regional issue salience.

Core riding fields:

- Riding id.
- Federal riding code.
- Name.
- Province or territory.
- Region.
- Geometry id for map.
- Urban/suburban/rural/northern classification.
- Population.
- Eligible voters.
- Expected turnout.
- Language profile.
- Income profile.
- Education profile.
- Age profile.
- Housing profile.
- Industry mix.
- Indigenous population share.
- Immigration/new Canadian share.
- Union density.
- Religious/social conservatism index.
- Incumbent party.
- Incumbent candidate.
- Open seat flag.
- Historical results by party.
- Current estimated vote share by party.
- Local campaign organization by party.
- Candidate quality by party.
- Local volatility.
- Strategic voting tendency.
- Split-ticket tendency, reserved for future systems.

## Riding Issue Values

Each riding should have 10 to 30 issue fields. Values should be stored on a normalized 0 to 100 scale:

- 0 = left/progressive/interventionist side of the issue.
- 50 = centrist or mixed.
- 100 = right/conservative/market-oriented side of the issue.

The UI can show each value as a horizontal red-to-blue gradient bar with the riding population marker placed along the bar. Where the issue does not fit left/right cleanly, the UI label should name the endpoints explicitly.

Recommended first 24 issue fields:

1. Economy and growth.
2. Cost of living.
3. Housing affordability.
4. Taxation.
5. Government spending.
6. Health care funding.
7. Climate action.
8. Energy and pipelines.
9. Natural resources.
10. Labour and unions.
11. Immigration levels.
12. Public safety and crime.
13. Drug policy.
14. Foreign policy and defence.
15. Canada-US relations.
16. Indigenous reconciliation.
17. French language and Quebec autonomy.
18. Regional alienation.
19. Agriculture and rural policy.
20. Technology, AI, and privacy.
21. Education and skills.
22. Seniors and pensions.
23. Social values.
24. Democratic reform and electoral fairness.

Issue metadata should define:

- Slug.
- Display name.
- Left endpoint label.
- Centre label.
- Right endpoint label.
- National salience.
- Regional salience overrides.
- Which parties own or struggle on the issue.
- Which leader traits amplify effects.

Example:

```json
{
  "slug": "housing_affordability",
  "name": "Housing Affordability",
  "left_label": "Public/non-profit buildout",
  "center_label": "Mixed supply and demand policy",
  "right_label": "Private supply and deregulation",
  "national_salience": 0.92
}
```

## Party Model

Parties should be simulated as national organizations with regional and riding-level strength.

Party fields:

- Name.
- Short name.
- Colour.
- Ideology vector by issue.
- Leader.
- National brand strength.
- Regional brand strength.
- Fundraising.
- Volunteer capacity.
- Campaign organization.
- Media discipline.
- Policy coherence.
- Scandal resistance.
- Debate strength.
- Ground game strength.
- Incumbency bonus.
- Voter ceiling.
- Voter floor.
- Strategic voting attractiveness.
- Coalition compatibility.

Party issue positions should use the same 0 to 100 scale as riding values. A party performs better in a riding when its position is close to the riding's value on high-salience issues, but leader image, candidate quality, strategic voting, history, and national mood can override pure issue matching.

## Leader Model

Leader attributes drive daily decisions and campaign effects.

Leader fields:

- Name.
- Party.
- Charisma.
- Competence.
- Trust.
- Empathy.
- Discipline.
- Debate skill.
- Media skill.
- Policy knowledge.
- Scandal risk.
- Stamina.
- Regional familiarity.
- French strength.
- English strength.
- Economic credibility.
- Working-class appeal.
- Youth appeal.
- Senior appeal.
- Quebec appeal.
- Western appeal.
- Ontario appeal.
- Atlantic appeal.
- Incumbency stature.

Leader stats should affect:

- Speech effectiveness.
- Debate performance.
- Scandal survival.
- Media cycle conversion.
- Regional visit bonuses.
- Fundraising.
- Volunteer enthusiasm.
- Candidate recruitment.
- Daily fatigue.

## Leadership Reviews and Party Conventions

Parties should have internal politics. If a party performs badly, the leader should not automatically stay forever.

Leadership triggers:

- Leader loses their own riding.
- Party fails to win government when expected.
- Party loses official opposition status.
- Party loses a major share of seats.
- Party falls below its historical floor.
- Party members lose confidence after repeated scandals.
- Leader voluntarily resigns after defeat.
- Fixed post-election leadership review.

Leadership review outcomes:

- Leader survives and gains internal stability.
- Leader survives narrowly and starts weakened.
- Leader resigns immediately.
- Party schedules a leadership convention.
- Interim leader takes over until the convention.

Convention system:

- Candidate recruitment phase.
- Endorsement phase.
- Debate phase.
- Membership sales/organizing phase.
- Ballot result.
- New leader selected.

Leadership candidate fields:

- Name.
- Faction.
- Region.
- Parliamentary experience.
- Public profile.
- Charisma.
- Competence.
- Ideological position by issue.
- Fundraising network.
- Endorsements.
- Member appeal.
- General-election appeal.
- Bilingual strength.
- Scandal risk.

Convention results should affect the next campaign:

- Party unity.
- Fundraising.
- Membership enthusiasm.
- Regional appeal.
- Issue repositioning.
- Media narrative.
- Risk of factional backlash.

The game can start with fixed real-world leaders, but long-running saves should allow leadership change and party repositioning.

## Governing Mode and Election Cycle

After election night, the game should not simply stop. The result should create a government term that turns the campaign into a long-running Canadian federal politics simulator.

Current implemented loop:

1. Election night produces final riding winners, seat totals, popular vote, and a government type.
2. A government term is created automatically from the winning party.
3. If the winner has 172 or more seats, the term starts as a majority government with higher confidence and a longer scheduled term.
4. If the winner has fewer than 172 seats, the term starts as a minority parliament and may have a confidence-support partner.
5. Each governing week creates government actions, opposition actions, Parliament events, party readiness snapshots, and a newspaper story.
6. Confidence, approval, economic conditions, affordability, stability, and mandate progress move each week.
7. Leadership reviews can resolve into conventions, ballots, and new leaders during the governing period.
8. Confidence can collapse on budget/confidence weeks, producing an early election.
9. If the term reaches its scheduled end, Parliament dissolves normally.
10. Dissolution automatically generates the next election campaign.

Governing metrics:

- Confidence: whether the government can survive Parliament.
- Approval: public evaluation of the government.
- Economic index: broad economic mood.
- Affordability index: cost-of-living mood.
- Stability index: institutional and caucus stability.
- Mandate progress: how much of the government's agenda it has delivered.
- Party readiness: how prepared each party is for the next election.
- Party unity: whether leadership and factions are settled.

Next-election handoff:

- The next campaign keeps the changed party leaders.
- The previous government's record becomes the incumbent record for the new election.
- Party brand, fundraising, organization, and leader effects carry forward.
- Incumbent riding parties are updated from the previous election winners.
- The player keeps control of the same party unless they start a different campaign.

Future expansions:

- Cabinet appointments and ministerial strengths.
- Explicit confidence agreements with policy concessions.
- Bills with committee/amendment stages.
- Scandals and inquiries over multiple weeks.
- By-elections.
- Cabinet shuffles.
- Party membership drives before conventions.
- Leadership debates and ranked convention ballots.
- Budget design and fiscal tradeoffs.
- International crises and federal-provincial negotiations.
- Opposition strategy selection by player or AI.

## Candidate Model

Each party can have a candidate in each riding.

Candidate fields:

- Name.
- Party.
- Riding.
- Incumbent flag.
- Local profile.
- Quality.
- Local reputation.
- Campaign skill.
- Fundraising skill.
- Ground game.
- Issue fit with riding.
- Scandal risk.
- Language fit.
- Community roots.
- Profession/background.

Candidate effects should be local. A great candidate can save a weak party in one riding. A poor or scandal-prone candidate can waste a national wave.

## Endorsements and National Groups

National, provincial, regional, and local groups can endorse a party, leader, or riding candidate. Endorsements should matter most when the group is trusted by the riding's voters and connected to a salient issue.

Group types:

- Labour unions.
- Business associations.
- Environmental organizations.
- Taxpayer/fiscal groups.
- Housing advocacy groups.
- Seniors organizations.
- Student/youth groups.
- Indigenous organizations.
- Immigrant/community organizations.
- Faith and social values organizations.
- Agriculture and rural groups.
- Energy and resource industry groups.
- Technology and privacy groups.
- Veterans and defence groups.
- Health care advocacy groups.
- Local chambers of commerce.
- Municipal or former political figures.
- Newspapers/editorial boards, if the game chooses to model endorsements.

Group fields:

- Name.
- Scope: national, province, region, riding, or media market.
- Issue focus.
- Ideological position.
- Trust level by region.
- Member/voter reach.
- Political activity level.
- Endorsement criteria.
- Backlash risk.
- Preferred parties.
- Relationship score with each party.

Endorsement effects:

- Boost issue credibility.
- Increase volunteer enthusiasm.
- Improve fundraising.
- Shift a narrow audience segment.
- Increase turnout among aligned voters.
- Create backlash among opposed voters.
- Trigger media coverage.

Endorsements should not simply add flat support. Example: a national labour endorsement helps more in union-heavy ridings and on affordability/labour messages, while a business endorsement helps more with economy-focused voters and can hurt with anti-corporate voters.

## Boosters and Campaign Surrogates

Boosters are people or organizations that actively join a campaign team. Unlike endorsements, boosters can be assigned, scheduled, and used. They give the campaign extra reach beyond the leader.

Booster examples:

- Former prime minister.
- Former cabinet minister.
- Popular local MP.
- Retiring respected MP.
- Premier or former premier.
- Mayor or local councillor.
- Celebrity supporter.
- Union organizer.
- Business leader.
- Environmental advocate.
- Community organizer.
- Faith/community leader.
- Indigenous leader.
- Youth influencer.
- Ethnic media personality.
- Policy expert.
- Campaign strategist.
- Fundraising chair.
- Debate coach.
- Crisis communications advisor.
- Local riding captain.

Booster scopes:

- National: affects country-wide narratives, fundraising, broad credibility, or major media.
- Regional: affects a province, territory, language community, or media market.
- Local: affects one riding or a cluster of nearby ridings.
- Demographic: affects a group such as youth, seniors, union households, new Canadians, farmers, or small-business owners.
- Issue-specific: affects credibility on a specific issue.

Booster fields:

- Name.
- Type.
- Scope.
- Home riding.
- Home province/region.
- Language strengths.
- Public profile.
- Trust rating.
- Controversy risk.
- Fundraising power.
- Media skill.
- Ground game skill.
- Speech skill.
- Issue expertise.
- Demographic reach.
- Regional reach.
- Party loyalty.
- Relationship with leader.
- Fatigue/stamina.
- Availability window.
- Cost or conditions to recruit.

Recruitment rules:

- Some boosters start with the party.
- Some can be recruited through relationship-building actions.
- Some require policy alignment.
- Some require a leadership, candidate, or faction connection.
- Some refuse to join if the campaign is too extreme, too moderate, too scandal-hit, or too unlikely to win.
- Some bring backlash from opposing voters.

Booster actions:

- Campaign in riding.
- Give local speech.
- Do regional media.
- Host fundraiser.
- Rally volunteers.
- Endorse candidate.
- Defend leader.
- Attack opponent.
- Validate policy announcement.
- Repair scandal damage with a specific audience.
- Improve candidate quality or ground game.
- Train local organizers.
- Mobilize turnout.

Booster effects:

- Local support lift.
- Regional support lift.
- National credibility lift.
- Fundraising increase.
- Volunteer/ground-game increase.
- Turnout increase among aligned voters.
- Issue salience increase.
- Reduced backlash on difficult policy.
- Improved media conversion.
- Faction unity or faction tension.

Boosters should have their own schedules. A national leader should not be the only active campaign piece on the board. The player should be able to send the leader to one place while boosters work other target ridings or media markets.

Booster balance rules:

- Boosters are strongest when their profile matches the target.
- A beloved local booster can matter more than a national celebrity in one riding.
- Overused boosters lose novelty and gain fatigue.
- Controversial boosters can help the base while hurting swing voters.
- A booster can become a liability if scandal, hypocrisy, or issue mismatch emerges.

## Polling Model

Polls should exist at several levels:

- National.
- Regional.
- Province/territory.
- Quebec-specific francophone/non-francophone.
- Demographic groups.
- Riding-level estimate.
- Seat projection.

Poll movement should include:

- True opinion movement.
- Polling noise.
- House effects by pollster.
- Sample error.
- Lag between public opinion and reported poll.
- Momentum narratives.

Daily hidden support should be separated from public polls:

- `true_support`: the actual simulated voter preference.
- `poll_support`: what public polls estimate.
- `reported_support`: what appears in news, with lag and noise.

This lets the game create uncertainty and prevents the player from seeing perfect information.

## Vote Share Calculation

At a high level, each party's riding vote share should be derived from:

```text
base_support
+ national_swing
+ regional_swing
+ issue_fit
+ leader_effect
+ local_candidate_effect
+ incumbency_effect
+ riding_visit_bonus
+ ad_effect
+ ground_game_effect
+ strategic_voting_effect
+ news_event_effect
+ random_campaign_noise
= raw_party_score
```

Raw party scores are then normalized into vote shares. Election day adds turnout and final volatility.

Suggested scoring details:

- `issue_fit`: weighted distance between riding values and party positions.
- `leader_effect`: leader approval multiplied by riding openness to the leader.
- `candidate_effect`: local candidate quality and scandal state.
- `incumbency_effect`: positive unless the incumbent is retiring or scandal-hit.
- `visit_bonus`: temporary local lift, stronger when leader and riding fit.
- `ad_effect`: depends on market coverage, message fit, saturation, and backlash risk.
- `ground_game_effect`: mostly turnout and persuasion among soft supporters.
- `strategic_voting_effect`: helps the locally viable anti-incumbent or anti-leading-party option.
- `noise`: higher in volatile, low-information, open-seat ridings.

## Leader Activities

Each day, leaders should choose 5 to 10 actions from a limited daily schedule. Every action costs time, effort, stamina, money, or opportunity. The leader can overwork, but fatigue increases mistake risk and lowers future effectiveness.

Recommended daily capacity:

- Normal day: 10 time blocks.
- Travel day: 8 to 10 time blocks depending on distance.
- Debate day: 6 time blocks plus mandatory debate/prep.
- Rest day: 4 light blocks, restores stamina.

Action cost fields:

- `time_blocks`: how much of the day it consumes.
- `effort`: mental/physical strain.
- `money_cost`: direct campaign spend.
- `staff_cost`: organizer/media team bandwidth.
- `target_scope`: national, region, province, media market, riding, or candidate.
- `location_required`: whether the leader must be physically present.
- `cooldown_days`: prevents repeating powerful actions too often.
- `effect_duration_days`: how long the effect lasts.
- `decay_rate`: how quickly the effect fades.
- `risk_level`: gaffe, backlash, fatigue, scandal, or opportunity risk.

Initial activity types:

- Visit riding.
- Regional tour.
- National speech.
- Policy announcement.
- Local targeted speech.
- Fundraiser.
- Volunteer rally.
- Media interview.
- Press conference.
- Debate preparation.
- Attack opponent.
- Defend against attack.
- Apologize/damage control.
- Candidate endorsement visit.
- Digital ad buy.
- TV/radio ad buy.
- Direct mail or texting push.
- Ground game investment.
- Opposition research.
- Internal organizing.
- Rest/recovery.
- Private stakeholder meeting.
- Meet mayor/local figure.
- Release platform plank.
- Visit workplace, school, farm, hospital, or community site.
- Hold town hall.
- Door-knock/photo opportunity with candidate.
- Record digital content.
- Call donors.
- Negotiate endorsement.
- Prepare candidate or local campaign team.
- Crisis briefing.

Each activity needs:

- Cost.
- Time slot.
- Target scope.
- Issue focus.
- Potential upside.
- Backlash risk.
- Leader stat modifiers.
- Local riding fit modifiers.
- Media amplification chance.
- Duration of effect.
- Decay curve.

Example leader actions:

| Action | Time | Effort | Main effect | Risk |
| --- | ---: | ---: | --- | --- |
| Move to another riding | 1-4 | 1-3 | Enables local actions, creates small visit effect | Lost time, fatigue |
| Give local speech | 2 | 3 | Local issue salience, riding support, media clips | Gaffe/backlash |
| Give national speech | 3 | 4 | National narrative, leader approval, issue ownership | Bigger backlash |
| Media interview | 1-2 | 2-3 | Depends on outlet reach and tone | Hostile interview |
| Fundraiser | 2 | 2 | Money, donor enthusiasm | Elitism/backlash if overused |
| Volunteer rally | 2 | 3 | Ground game, turnout, local morale | Low effect if poor fit |
| Policy announcement | 3 | 4 | Issue ownership, national/regional movement | Costing/credibility attack |
| Debate prep | 2-5 | 2-4 | Debate performance | Opportunity cost |
| Damage control | 2-4 | 4 | Reduces scandal/event penalty | Keeps bad story alive |
| Rest | 2-6 | -3 | Recovers stamina | Opponents set agenda |

The UI should show a daily schedule meter. A player can queue actions until time blocks are full, then advance the day.

## Speeches

Speeches are one of the key ways the player changes issue preferences and party support.

Speech inputs:

- Speaker.
- Location/riding.
- Audience.
- Issue focus.
- Tone.
- Policy detail level.
- Attack/positive balance.
- National vs local framing.
- Language.
- Media strategy.

Speech outputs:

- Riding issue movement.
- Local party support change.
- Regional media effect.
- National narrative effect.
- Leader approval change.
- Opponent response trigger.
- Backlash chance.

Important rule: speeches should rarely move a whole riding dramatically. Most speeches should change salience, enthusiasm, and soft voters. Major movement should require repeated visits, a powerful event, excellent fit, or opponent mistakes.

## Leader Debates

The campaign should include several debates. Canada commonly has official English and French leaders' debates, and the game should also support optional regional, issue-specific, youth, economic, climate, northern, and local candidate debates.

Debate types:

- Official English leaders' debate.
- Official French leaders' debate.
- National economy debate.
- National foreign policy/security debate.
- Climate/energy debate.
- Quebec-focused debate.
- Western Canada/resource debate.
- Atlantic Canada/regional affordability debate.
- Northern/Indigenous issues forum.
- Youth/student debate.
- Local riding candidate debate.

Debate fields:

- Name.
- Date.
- Language.
- Host/media outlet.
- Location.
- Invited parties/leaders.
- Participation criteria.
- Issues covered.
- Audience demographics.
- Expected viewership.
- Moderator difficulty.
- Format: open debate, timed answers, town hall, one-on-one, panel.
- Stakes.
- Spin window after the debate.

Debate preparation actions:

- Full debate prep day.
- Short briefing.
- Mock debate.
- Opposition research.
- Practice French/English delivery.
- Practice attack lines.
- Practice defensive answers.
- Prepare local/regional examples.
- Rest before debate.

Debate performance should depend on:

- Leader debate skill.
- Policy knowledge.
- Discipline.
- Charisma.
- Language strength.
- Fatigue.
- Scandal pressure.
- Prep time.
- Issue fit.
- Opponent attacks.
- Moderator difficulty.

Debate outputs:

- Leader approval movement.
- National support movement.
- Regional/language-community movement.
- Issue ownership changes.
- Media clips.
- Fundraising/volunteer surge.
- Gaffe or breakthrough moment.
- Post-debate polling bump.
- Spin-room narrative.

Debate moments:

- Strong opening.
- Effective attack.
- Failed attack.
- Memorable line.
- Policy mistake.
- Empathy moment.
- Angry exchange.
- Moderator clash.
- Language stumble.
- Opponent fact-check.
- Viral clip.

Debate aftermath:

- Media outlets judge winners differently depending on audience and editorial tone.
- Boosters can do post-debate spin.
- Opponents can amplify gaffes.
- A clear winner gets a short-term national bump and a longer credibility effect.
- A weak performance can be repaired with apology, clarification, local visits, or strong follow-up interviews.
- Local candidate debates should mostly affect one riding, but clips can travel in close or high-profile races.

## Media System

Media coverage should feed back into polls. A leader can give interviews, buy ads, generate earned media, or suffer hostile coverage. Media should be modeled by outlet, market, language, audience, trust, reach, and ideological tone.

Media levels:

- National English.
- National French.
- Parliamentary/political.
- Province-wide.
- Regional.
- Local riding/community.
- Ethnic/community.
- Digital/social.

Seed outlet examples:

- CBC News.
- Radio-Canada.
- CTV News.
- Global News.
- CPAC.
- The Canadian Press.
- The Globe and Mail.
- Toronto Star.
- National Post.
- La Presse.
- Le Devoir.
- TVA/LCN.
- CityNews.
- Local radio.
- Local newspapers.
- Campus/community media.
- Indigenous media.
- Ethnic-language media.

Media outlet fields:

- Name.
- Type: TV, radio, newspaper, digital, wire service, parliamentary, podcast, community.
- Scope.
- Primary language.
- Home market.
- Covered provinces/regions/ridings.
- Reach.
- Political audience.
- Trust by demographic.
- Interview difficulty.
- Hostility/friendliness by party.
- Issue interests.
- Amplification multiplier.
- Local poll effect weight.

Media interview inputs:

- Leader.
- Outlet.
- Location.
- Topic.
- Tone.
- Preparation level.
- Message discipline.
- Whether the outlet is friendly, neutral, or hostile.

Media interview outputs:

- National support movement if the outlet has national reach.
- Local/regional support movement where the outlet is trusted.
- Leader approval movement.
- Issue salience movement.
- Clip generation for social media.
- Gaffe/backlash chance.
- Opponent response chance.

Coverage rules:

- Local media should affect nearby ridings more than national numbers.
- French-language media should matter more in Quebec and francophone communities.
- National TV clips can escape the original market and become a national story.
- Wire services can turn a local event into national coverage.
- Repeated friendly interviews can saturate and lose effectiveness.
- Hostile interviews can be worth doing if the leader has high discipline and needs to reach skeptical voters.

## Advertising and Communications

Advertising should be related to media markets rather than only ridings.

Ad types:

- National TV.
- Regional TV.
- Local radio.
- Digital video.
- Search/social ads.
- Direct mail.
- Text/email.
- Outdoor/billboard.
- Newspaper ads.
- Ethnic-language ads.

Ad fields:

- Message issue.
- Tone: positive, contrast, attack, fear, hope, competence, local.
- Target geography.
- Target demographic.
- Buy size.
- Creative quality.
- Saturation.
- Backlash risk.
- Fact-check risk.
- Decay curve.

Ad effects should depend on:

- Message fit with riding values.
- Party credibility on the issue.
- Whether voters already know the leader.
- Local media market coverage.
- Opponent counter-message.
- Ad fatigue.

## Event System

Events make the campaign feel alive. They should be generated from templates and resolved by rules.

Event categories:

- Economic news.
- Foreign affairs.
- Scandal.
- Candidate mistake.
- Policy backlash.
- Endorsement.
- Debate moment.
- Regional crisis.
- Natural disaster.
- Labour dispute.
- Court ruling.
- Poll shock.
- Media gaffe.
- Social media surge.
- Protest.
- Interest group campaign.
- Third-party advertising.

Event fields:

- Scope.
- Affected issues.
- Affected parties.
- Affected leaders.
- Affected ridings or regions.
- Severity.
- Duration.
- Decay.
- Visibility.
- Counterplay options.
- AI response options.

## Election Night Live Count

Election night should be a live phase, not a single instant result screen. Votes should come in riding by riding and poll by poll. Early results should reflect the same underlying campaign model but include turnout, reporting order, special ballots, advance votes, and uncertainty.

Election night phases:

1. Polls close by region/time zone.
2. Initial advance/special ballot indicators where available.
3. First polls report in each riding.
4. Media projections begin for safe ridings.
5. Toss-up ridings update as more polls report.
6. Seat count crosses minority/majority thresholds.
7. Final preliminary result.
8. Validation/recount watchlist.

Live reporting fields:

- Riding.
- Polls reporting.
- Total polls.
- Reported votes by candidate.
- Estimated remaining vote.
- Advance/special ballot share.
- Turnout estimate.
- Current leader.
- Margin.
- Projection status: too early, leaning, likely, elected, recount watch.
- Confidence.

Vote count simulation:

- Generate final true turnout by riding.
- Generate final vote totals by candidate from true support, candidate quality, ground game, turnout enthusiasm, and election-day noise.
- Split totals into reporting batches.
- Assign each batch a reporting time.
- Make some batch types politically distinct: advance polls, urban polls, rural polls, campus polls, remote polls, mail/special ballots.
- Update the live UI every simulated minute or every reporting batch.

Turnout effects:

- Enthusiasm increases turnout among party supporters.
- Ground game increases turnout in targeted ridings.
- Bad weather or local disruption can depress turnout.
- Advance voting can bank votes before late campaign events.
- Younger voters and low-propensity voters should have higher turnout volatility.
- Senior voters and habitual voters should be more stable.

Election-night drama rules:

- A party can lead early and fade if friendly polls report first.
- Remote ridings can report slowly.
- Close ridings can remain uncalled.
- Recounts should trigger when margins are extremely narrow.
- Preliminary and validated results can differ slightly.
- The player should see paths to government update live.

Election night UI:

- Live national seat counter.
- Government threshold tracker.
- Riding results map.
- Time-zone/province close schedule.
- List of called seats.
- List of uncalled/toss-up seats.
- Party popular vote.
- Leader riding status.
- Alerts for flips, losses, holds, recount-watch ridings, and majority/minority thresholds.

## Backend Architecture

The backend should be organized around simulation services rather than controller-heavy logic.

Laravel 9 application structure:

- `Models`
  - `ElectionGame`
  - `CampaignDay`
  - `Party`
  - `Leader`
  - `Riding`
  - `RidingIssueProfile`
  - `Issue`
  - `Candidate`
  - `Poll`
  - `CampaignAction`
  - `CampaignEvent`
  - `MediaOutlet`
  - `MediaMarket`
  - `InterestGroup`
  - `Endorsement`
  - `Booster`
  - `BoosterAssignment`
  - `Debate`
  - `DebateParticipant`
  - `DebateMoment`
  - `DailyArticle`
  - `DailyBriefing`
  - `CampaignFinanceLedger`
  - `CampaignOffice`
  - `CampaignStaffer`
  - `VoterBloc`
  - `AdvanceVoteSnapshot`
  - `LocalDisruption`
  - `CandidateNomination`
  - `GovernmentRecord`
  - `GovernmentFormation`
  - `AnalyticsReport`
  - `TutorialStep`
  - `SaveGame`
  - `SimulationBatchRun`
  - `ScenarioPreset`
  - `LeadershipContest`
  - `LeadershipCandidate`
  - `ElectionResult`
  - `ElectionNightBatch`
  - `SeatProjection`
- `Services`
  - `ElectionGenerator`
  - `CampaignDaySimulator`
  - `LeaderActionResolver`
  - `SpeechResolver`
  - `PollingSimulator`
  - `RidingSupportCalculator`
  - `EventGenerator`
  - `MediaCoverageResolver`
  - `EndorsementResolver`
  - `BoosterRecruitmentService`
  - `BoosterAssignmentResolver`
  - `DebateSimulator`
  - `DailyNewsGenerator`
  - `NarrativeSummaryService`
  - `CampaignFinanceService`
  - `CampaignOfficeService`
  - `StaffAssignmentResolver`
  - `VoterBlocSupportCalculator`
  - `AdvanceVotingSimulator`
  - `LocalDisruptionResolver`
  - `CandidateNominationService`
  - `GovernmentRecordService`
  - `GovernmentFormationSimulator`
  - `CampaignAnalyticsService`
  - `TutorialService`
  - `SaveReplayService`
  - `SimulationBatchRunner`
  - `LeadershipConventionSimulator`
  - `ElectionDaySimulator`
  - `ElectionNightSimulator`
  - `SeatProjectionService`
  - `MapDataService`
- `Controllers`
  - `GameController`
  - `CampaignController`
  - `RidingController`
  - `PollController`
  - `StatsController`
  - `AdminGenerationController`
- `Resources/API`
  - Game state.
  - Riding details.
  - Map features.
  - Poll summaries.
  - Daily reports.
  - Election results.

## Database Tables

Minimum table plan:

- `election_games`
- `campaign_days`
- `parties`
- `leaders`
- `issues`
- `party_issue_positions`
- `ridings`
- `riding_issue_profiles`
- `riding_demographics`
- `candidates`
- `campaign_actions`
- `campaign_events`
- `media_outlets`
- `media_markets`
- `media_market_ridings`
- `media_coverage_events`
- `interest_groups`
- `endorsements`
- `boosters`
- `booster_party_relationships`
- `booster_assignments`
- `booster_daily_snapshots`
- `debates`
- `debate_participants`
- `debate_moments`
- `daily_briefings`
- `daily_articles`
- `campaign_finance_ledgers`
- `campaign_offices`
- `campaign_staffers`
- `staff_assignments`
- `voter_blocs`
- `riding_voter_bloc_profiles`
- `advance_vote_snapshots`
- `local_disruptions`
- `candidate_nominations`
- `government_records`
- `government_formations`
- `analytics_reports`
- `tutorial_steps`
- `save_games`
- `simulation_batch_runs`
- `scenario_presets`
- `leadership_contests`
- `leadership_candidates`
- `leadership_ballots`
- `polls`
- `poll_entries`
- `seat_projections`
- `election_results`
- `election_result_entries`
- `election_night_batches`
- `election_night_calls`
- `riding_daily_snapshots`
- `party_daily_snapshots`
- `leader_daily_snapshots`

High-value snapshots:

- Riding support by party per day.
- Party national support per day.
- Leader approval per day.
- Issue salience per day.
- Event effects and expiry.
- Booster assignment effects and fatigue.
- Debate moments and post-debate effects.
- Finance, office, staff, voter bloc, advance vote, and analytics snapshots where needed.

Snapshots will make charts, debugging, and replay much easier.

## Generation Pages

The backend/admin UI needs pages to generate, inspect, and tune simulations.

Generation pages:

- New election setup.
- Party setup.
- Leader setup.
- Riding data import.
- Riding issue profile generator.
- Candidate generator.
- Booster generator.
- Debate schedule generator.
- Campaign finance setup.
- Staff and office generator.
- Voter bloc profile generator.
- Candidate nomination setup.
- Government record setup for incumbent scenarios.
- Scenario preset manager.
- Poll baseline generator.
- Event template manager.
- Simulation settings.
- Balance batch runner.
- Test simulation runner.
- Seed data health check.

New election setup should allow:

- Election name.
- Start date.
- Election date.
- Campaign length.
- Player party.
- Difficulty.
- Realistic/sandbox mode.
- Randomness level.
- Include scandals toggle.
- Include minor parties toggle.
- Starting poll preset.
- Historical baseline preset.
- Incumbent government record preset.
- Finance difficulty preset.
- Analytics/data quality preset.

## Stats Pages

Stats pages should help players understand the campaign and help developers debug the simulation.

Player-facing stats:

- National polling chart.
- Seat projection chart.
- Regional polling.
- Leader approval.
- Booster roster and assignments.
- Cash, spending, and fundraising.
- Staff and office strength.
- Voter bloc movement.
- Advance vote estimate.
- Analytics recommendations.
- Issue salience.
- Momentum tracker.
- Fundraising and spending.
- Riding watchlist.
- Toss-up ridings.
- Best pickup opportunities.
- Seats at risk.
- Path to majority.
- Daily news and event log.
- Upcoming debate and event calendar.

Developer/admin stats:

- Support calculation breakdown by riding.
- Action effect audit.
- Poll noise vs true support.
- Event effect stack.
- Debate scoring breakdown.
- Daily article source/action links.
- AI decision log.
- Random seed and reproducibility.
- Balance warnings.
- Batch simulation reports.

## Frontend Architecture

The front page should be the game dashboard, not a marketing page.

Main layout:

- Daily newspaper/front-page briefing at the top or in a prominent column.
- Canada riding map as the primary surface.
- Riding search/list side panel.
- Selected riding detail panel.
- Campaign top bar with date, days remaining, player party, money, stamina, and poll summary.
- Resource strip for cash, staff capacity, office strength, analytics confidence, and advance vote status.
- Bottom or side action tray for daily campaign choices.
- Alerts/news feed.

Main views:

- Dashboard/map.
- Riding detail.
- Polls.
- Seat projection.
- Leader/party page.
- Campaign actions.
- Daily report.
- Stats.
- Admin/generation pages.

## Daily Newspaper and Front Page

The front page should feel like a campaign morning briefing mixed with a newspaper front page. Each day should generate readable articles that explain what happened yesterday, what leaders and candidates did, where they went, where polls moved, and what is coming next.

Front page modules:

- Main headline.
- Lead campaign story.
- Poll tracker snapshot.
- Leader whereabouts.
- Riding spotlight.
- Coming events.
- Debate calendar.
- Endorsements/boosters watch.
- Scandal or controversy watch.
- Regional headlines.
- Local riding headlines for watched ridings.
- Optional editorial/cartoon-style flavour item later.

Article types:

- Poll movement story.
- Leader travel story.
- Speech story.
- Media interview recap.
- Debate preview.
- Debate result.
- Endorsement story.
- Booster campaign stop story.
- Candidate local story.
- Scandal/damage-control story.
- Riding toss-up story.
- Fundraising story.
- Event preview.
- Election-night preview during final days.

Daily article fields:

- Game.
- Campaign day.
- Headline.
- Subheadline.
- Article type.
- Scope: national, region, province, media market, riding.
- Related party.
- Related leader.
- Related candidate.
- Related booster.
- Related riding.
- Related issue.
- Tone.
- Importance.
- Source action/event id.
- Public poll deltas referenced.
- Hidden truth flag for debugging only.
- Body text.

Article generation rules:

- Articles should be generated from actual campaign actions, poll changes, debate moments, events, and upcoming schedule records.
- The main headline should pick the highest-importance story of the day.
- Poll articles should mention direction and momentum, not expose perfect hidden support.
- Leader travel articles should show where each major leader is or was.
- Upcoming event articles should preview debates, major speeches, campaign launches, deadlines, advance polls, and election night.
- The player should be able to click from an article into the related riding, leader, action, poll, debate, or event.
- Repeated article templates should vary wording so the campaign does not feel mechanical.
- Different simulated newspapers/outlets can frame the same event differently in later versions.

Example daily briefing layout:

1. Main headline: "Liberals push housing message as Conservatives target suburban Ontario."
2. Poll box: national and regional movement with uncertainty.
3. Where they are: each leader's location and planned action.
4. Coming up: debate tomorrow, advance polls in four days, major rally tonight.
5. Watchlist: five ridings with the biggest movement.

## Map Requirements

The map must support:

- All 343 federal ridings.
- Click/tap riding selection.
- Hover labels on desktop.
- Search by riding name.
- Filter by province/territory.
- Filter by competitiveness.
- Colour by leading party.
- Colour by margin.
- Colour by selected issue value.
- Colour by turnout.
- Zoom and pan.
- Mobile-friendly list fallback.

Map data options:

1. Store simplified GeoJSON locally and serve it from the backend.
2. Use TopoJSON for smaller payloads.
3. Start with province-level placeholder map for prototype, then upgrade to real riding geometries.

Recommendation:

- Prototype with a list and simplified map if needed.
- For the first real release, import simplified federal riding GeoJSON/TopoJSON and cache generated map payloads.

## Riding Detail UI

When a riding is selected, show:

- Name and province.
- Current leading party and margin.
- Estimated vote share by party.
- Historical result.
- Incumbent/candidates.
- Demographic tags.
- Turnout estimate.
- Competitiveness.
- Local events.
- Recent leader visits.
- Issue bars.
- Local campaign organization.
- Recommended actions.

Issue bar:

- Label.
- Red-to-blue gradient.
- Population marker.
- Party position markers if useful.
- Salience indicator.
- Recent movement delta.

## Daily Action UI

The player should pick from action cards or compact controls:

- Leader travel destination.
- Speech issue.
- Speech tone.
- Ad target.
- Fundraising choice.
- Debate/media choice.
- Defensive response if needed.

Each action should preview:

- Cost.
- Expected effect range.
- Risk.
- Target ridings/regions.
- Leader stamina impact.
- Message fit.

The preview should avoid exact hidden math unless the difficulty setting allows it.

## AI Opponent System

Opponent parties should make plausible campaign decisions.

AI inputs:

- Current polls.
- Seat path.
- Leader strengths.
- Available money.
- Vulnerable ridings.
- Top issues.
- Recent events.
- Player actions.

AI strategies:

- Defend base.
- Expand into target region.
- Attack front-runner.
- Squeeze third party.
- Focus on leader image.
- Run policy-heavy campaign.
- Run negative campaign.
- Stabilize after scandal.
- Maximize turnout.

AI should have personality profiles by party and leader so every opponent does not feel identical.

## Difficulty Modes

Easy:

- More transparent polling.
- Larger effect previews.
- Lower opponent efficiency.
- Fewer severe scandals.

Normal:

- Moderate uncertainty.
- Balanced AI.
- Polling noise.

Hard:

- Less exact information.
- Smarter AI.
- Higher backlash risk.
- More expensive targeting.

Simulation sandbox:

- User can tune everything.
- Debug numbers visible.
- Can reroll days or events.

## Realism and Balance Principles

The game should feel Canadian without becoming a spreadsheet that only political scientists can enjoy.

Rules:

- Regional politics matter.
- Quebec should have distinct issue and party dynamics.
- Bloc support should be Quebec-only or nearly Quebec-only.
- National swings should not affect every riding equally.
- Local candidates and incumbency matter.
- Strategic voting matters, especially in close Liberal-Conservative-NDP contests.
- Vote efficiency matters: popular vote winner may not win the most seats.
- Polls should be useful but imperfect.
- Speeches and visits should matter locally but decay over time.
- Repeated coherent messaging should beat random daily issue-hopping.
- Debates should be rare, high-stakes events with preparation, performance, media spin, and post-debate polling effects.
- Newspaper/front-page stories should explain the simulation in plain language and help the player decide what to do next.

## Additional Core Systems

The following systems should be part of the full design. We will not model legal/election-rule enforcement in detail for the first major version, except where light flavour is needed for debates, recounts, or candidate registration.

### Money and Spending

Campaigns need cash, burn rate, and tradeoffs.

Finance fields:

- Cash on hand.
- Daily fundraising.
- Daily operating cost.
- Ad spend by market.
- Travel spend.
- Staff spend.
- Event spend.
- Polling/analytics spend.
- Fundraising efficiency.
- Donor enthusiasm.
- Small-dollar donor strength.
- Major donor network strength.

Money should affect:

- How many ads can run.
- How many staff and offices can be maintained.
- Travel pace.
- Polling and analytics quality.
- Event size.
- Digital reach.
- Endgame turnout push.

Money should not directly buy votes. It should amplify message delivery, organization, polling quality, and turnout.

### Staff and Campaign Offices

The party should have a national war room and optional regional/local campaign offices.

Office types:

- National headquarters.
- Regional office.
- Province/territory office.
- Media market office.
- Riding campaign office.

Staff roles:

- Campaign manager.
- Communications director.
- Policy director.
- Field director.
- Regional organizer.
- Local campaign manager.
- Data analyst.
- Fundraising lead.
- Debate coach.
- Crisis communications lead.
- Volunteer coordinator.

Staff effects:

- Better action efficiency.
- Lower gaffe risk.
- Better debate prep.
- Better media response.
- Better local ground game.
- Faster scandal recovery.
- Better voter contact and turnout.
- Better data quality.

Staff can make mistakes:

- Bad briefing.
- Overbooked leader.
- Poor local event optics.
- Data error.
- Missed riding opportunity.
- Message contradiction.

### Voter Blocs

Ridings should be made of voter blocs, not only one average ideology score.

Recommended voter blocs:

- Urban progressives.
- Suburban families.
- Rural conservatives.
- Working-class union households.
- Small-business owners.
- Seniors.
- Youth/students.
- New Canadians.
- Francophone Quebec nationalists.
- Federalist Quebec moderates.
- Indigenous voters.
- Resource-sector workers.
- Public-sector workers.
- Affluent professionals.
- Low-income renters.
- Farmers/agricultural voters.

Voter bloc fields:

- Share of riding.
- Turnout propensity.
- Persuadability.
- Party loyalty.
- Issue salience.
- Media trust profile.
- Leader affinity.
- Local candidate sensitivity.
- Strategic voting tendency.

This gives the simulator a better way to explain why a speech, ad, debate, or booster moved one riding but not another.

### Advance Voting

Some votes should be banked before election day. Late events can still move polls, but they should not affect voters who already voted.

Advance voting fields:

- Advance vote days.
- Vote share already banked by party.
- Turnout by voter bloc.
- Riding advance turnout.
- Special/mail ballot share.
- Campus/community vote share.
- Remote vote share.

Effects:

- Strong ground game banks votes early.
- Late scandals hurt less if a party already banked support.
- Late surges are capped by remaining unvoted electorate.
- Advance vote reports can become newspaper stories without revealing exact final results.

### Weather and Local Disruptions

Local disruption events add texture and risk.

Disruption types:

- Storm or extreme weather.
- Travel delay.
- Venue cancellation.
- Technical failure during debate or rally.
- Local emergency.
- Major traffic/transit disruption.
- Candidate illness.
- Protest.
- Power outage.
- Media feed failure.

Effects:

- Cancel or weaken leader actions.
- Depress turnout in specific ridings.
- Change news coverage.
- Force crisis response.
- Make a leader look compassionate or opportunistic depending on response.
- Slow election-night reporting in affected ridings.

### Candidate Nominations

Candidate quality should come from a nomination process.

Nomination states:

- No candidate.
- Searching.
- Contested nomination.
- Acclaimed candidate.
- Star candidate.
- Parachute candidate.
- Incumbent re-nominated.
- Candidate replaced.

Nomination effects:

- Star candidates add local credibility and media attention.
- Contested nominations can build energy or leave factional wounds.
- Parachute candidates may have high profile but weak local roots.
- Late candidate replacement hurts organization.
- Acclaimed local candidates can quietly improve ground game.

### Incumbent Government Record

If a party is governing, the campaign should evaluate its record.

Government record fields:

- Economic approval.
- Cost-of-living approval.
- Health care/federal transfer reputation.
- Housing record.
- Climate/energy record.
- Foreign policy/security record.
- Ethics/scandal burden.
- Competence reputation.
- Promise-keeping score.
- Regional fairness score.
- Leader prime-ministerial stature.

Effects:

- Incumbent parties get governing credibility.
- Incumbent parties also carry blame for national problems.
- Opposition parties can attack weak records.
- Good records improve trust and competence.
- Bad records raise volatility and change-voter appetite.

### Minority Parliament and Government Formation

After election night, the result should lead into government formation.

Outcomes:

- Majority government.
- Minority government.
- Opposition plurality.
- Confidence agreement.
- Informal issue-by-issue support.
- Leadership resignation.
- Hung parliament crisis.
- Snap second election risk in long-running saves.

Formation fields:

- Seat totals.
- Popular vote.
- Incumbent advantage.
- Party compatibility.
- Leader relationships.
- Confidence willingness.
- Policy concessions.
- Public legitimacy narrative.

This system can be mostly post-election flavour in the MVP, then become a long-term save mechanic later.

### Regional Campaign Operations

Regional offices should drive strategy below the national level.

Regional operation fields:

- Region/province/media market.
- Office level.
- Staff count.
- Volunteer capacity.
- Local data quality.
- Candidate support quality.
- Local message discipline.
- Target riding list.
- Budget allocation.

Effects:

- Improves local action efficiency.
- Improves riding-level polling accuracy.
- Boosts turnout.
- Helps local candidates respond to events.
- Finds pickup opportunities.
- Reduces wasted leader visits.

### Data and Analytics

The player should have imperfect tools for targeting.

Analytics outputs:

- Riding priority score.
- Pickup chance.
- Hold risk.
- Persuasion opportunity.
- Turnout opportunity.
- Best message by riding.
- Best booster by riding.
- Polling confidence.
- Data quality warning.

Analytics quality depends on:

- Money spent.
- Staff skill.
- Polling frequency.
- Regional office quality.
- Voter file quality.
- Ground-game feedback.

Bad analytics should sometimes mislead the player, especially on hard difficulty.

### Accessibility and Language Outreach

Language and accessibility should matter in campaigning.

Outreach fields:

- English capacity.
- French capacity.
- Indigenous-language outreach.
- Ethnic-language outreach.
- Accessible event quality.
- Rural/northern access quality.
- Digital accessibility.

Effects:

- Better reach into language communities.
- Better debate performance in each language.
- Better local event reception.
- More trust in communities that are often ignored.
- Lower backlash from tone-deaf campaign choices.

### Tutorial and Onboarding

The first campaign should teach the game without flattening it.

Tutorial flow:

1. Pick a party.
2. Inspect national polls.
3. Inspect one riding.
4. Read the daily newspaper.
5. Schedule leader actions.
6. Assign a booster.
7. Buy a small ad.
8. Respond to an event.
9. Prepare for a debate.
10. Advance to election night.

The tutorial should use real UI and gentle prompts, not a separate artificial mode.

### Save and Replay

The game should be deterministic when using the same seed.

Save/replay fields:

- Game seed.
- Scenario preset.
- Current day.
- Player party.
- Full campaign state.
- Action history.
- Event history.
- Poll history.
- Newspaper history.
- Election-night replay batches.

Replay features:

- Campaign timeline.
- Day-by-day map rewind.
- Poll chart playback.
- Election-night replay.
- Exportable result summary.

### Difficulty and Balance Tools

Because the simulation will be complex, balance tools are mandatory.

Tools:

- Run 100/500/1000 simulated campaigns.
- Compare average seat distributions.
- Detect overpowered actions.
- Detect stuck parties.
- Detect impossible comeback scenarios.
- Detect too-random election nights.
- Compare poll error against final result.
- Show action effect distributions.
- Show voter bloc movement.
- Scenario presets for common campaign starts.

These tools should be admin-only but built early enough that tuning does not become guesswork.

## MVP Scope

The first playable MVP should include:

- Create new election game.
- Generate parties, leaders, ridings, candidates, and issue profiles.
- Dashboard with riding list and placeholder or simplified map.
- Click/select riding and view details.
- 24 issue bars per riding.
- Daily action selection for player party.
- Leader daily schedule with time/effort costs.
- Basic AI actions for other parties.
- Basic media interview and coverage effects.
- Basic endorsement system.
- Basic booster roster and booster assignment system.
- Debate schedule and at least one simulated debate.
- Daily newspaper/front-page briefing.
- Basic campaign cash and spending.
- Basic staff/office strength by region.
- Basic voter blocs for turnout and persuasion.
- Basic advance-vote banking in the final stretch.
- Basic data/analytics recommendations.
- Daily support updates.
- National and regional polls.
- Election day simulation with simple live results.
- Seat results page.

MVP can fake or simplify:

- Exact riding geometries.
- Deep demographics.
- Pollster house effects.
- Complex media cycles.
- Full admin tuning.
- Full leadership convention simulation.
- Rich article prose and multiple simulated editorial voices.
- Deep staff mistakes, nomination fights, and government formation.
- Full tutorial and replay polish.

## Build Phases

### Phase 1: Foundation

- Create Laravel app structure or fit into existing module pattern.
- Add election game models and migrations.
- Add seeders for parties, leaders, boosters, issues, and sample ridings.
- Add base scenario presets, deterministic game seeds, and save-game records.
- Add game generation service.
- Add basic dashboard route.
- Add riding list and riding detail view.

### Phase 2: Riding and Issue Engine

- Implement issue metadata.
- Generate riding issue profiles.
- Generate voter bloc profiles.
- Generate party issue positions.
- Build issue fit scoring.
- Build voter bloc turnout and persuasion scoring.
- Add support calculation breakdown.
- Show red-to-blue issue bars in UI.

### Phase 3: Campaign Day Simulation

- Add campaign day records.
- Add player actions.
- Add action time blocks, effort, stamina, and cooldowns.
- Add leader activity resolver.
- Add booster assignments and booster action resolver.
- Add basic campaign finance, staff, and office capacity.
- Add AI action generator.
- Add basic travel and location requirements.
- Add daily support updates.
- Add daily newspaper/front-page generator.
- Add daily report page.

### Phase 4: Media, Endorsements, Polling, and Stats

- Add media outlets and media markets.
- Add interviews and media coverage effects.
- Add national/local endorsement groups.
- Add booster recruitment and booster media effects.
- Add debates, debate prep actions, debate scoring, and post-debate media spin.
- Add true support vs public poll support.
- Add polling noise.
- Add national, regional, and riding estimates.
- Add charts.
- Add seat projection.
- Add stats/debug pages.
- Add analytics recommendations and data quality confidence.

### Phase 5: Map

- Import simplified Canadian federal riding geometry.
- Link geometry to riding records.
- Render map with party colours.
- Add click, hover, search, province filters, and margin colouring.
- Add mobile list fallback.

### Phase 6: Events, Speeches, and Balance

- Add event templates.
- Add speech generator/resolver.
- Add local disruption resolver.
- Add weather/travel/venue disruption events.
- Add candidate nomination states.
- Add incumbent government record effects.
- Add media cycles and backlash.
- Add issue salience changes.
- Add decay curves.
- Tune balance using repeatable simulation seeds.

### Phase 7: Election Day and Results

- Add advance vote banking before election day.
- Simulate turnout.
- Resolve every riding.
- Generate election-night reporting batches.
- Add live election-night result updates.
- Add riding calls and recount-watch logic.
- Produce seat totals.
- Produce popular vote.
- Produce government type.
- Show result map.
- Show riding recount/toss-up summaries.
- Add post-election report.

### Phase 8: Leadership and Long-Term Saves

- Add post-election leadership reviews.
- Add leadership contests and conventions.
- Add interim leaders.
- Add party unity/faction effects.
- Add government formation and minority parliament outcomes.
- Let new leaders reposition parties before the next campaign.

### Phase 9: Polish, Tutorial, Replay, and Balance Tools

- Add guided tutorial/onboarding.
- Add campaign replay timeline.
- Add election-night replay.
- Add batch simulation runner.
- Add scenario preset manager.
- Add balance reports for actions, parties, voter blocs, and election-night volatility.

## Technical Risks

- Riding geometry can be heavy; simplify before shipping.
- Simulation can become hard to debug without snapshots and calculation logs.
- Issue-position math can make results feel too deterministic if not mixed with history, leader image, and local candidate effects.
- Daily actions can become overwhelming; UI should start with a few high-impact choices.
- Real political data changes often; seed data should be editable.
- Colour semantics can be tricky because Canadian party colours do not map perfectly to left/right ideology. Party colours and issue-gradient colours should be visually distinct.
- Media lists and local outlet reach will need seed data maintenance.
- Election-night reporting should feel uncertain without feeling random or unfair.
- SQLite is fine for the first playable version, but high-volume snapshots and live election-night batches need indexes and compact writes.
- Boosters can become overpowered if their effects stack without fatigue, diminishing returns, and local fit checks.
- Daily articles can become repetitive unless generated from varied templates and real campaign state.
- Debate effects can become too swingy unless split between short-term media bump and longer-term credibility changes.
- Voter blocs can make the model hard to explain unless the UI summarizes movement clearly.
- Finance and staff systems can become chores if every small expense needs manual attention.
- Advance voting must limit late swings without making the final week feel pointless.
- Analytics recommendations should be helpful but imperfect, especially at higher difficulty.
- Batch simulation tools need deterministic seeds or balance debugging will be painful.

## Open Design Questions

- Should the player always control a party, or can they control a leader personally?
- Should the game use real riding names from the start or fictionalized ridings for balance?
- Should real party leaders be default, optional, or only seed examples?
- How much hidden information should the player have?
- Should speeches be generated from templates, manually selected options, or free-text prompts later?
- Should scandals be purely random, trait-driven, or tied to risky campaign actions?
- Should the map be built first with actual riding geometry or introduced after the simulation MVP works?
- Should leadership conventions happen only after elections, or can leadership crises happen mid-parliament?
- Should media outlets use real names by default or fictionalized equivalents?
- Should live election-night calls be made by the game engine, simulated media networks, or both?
- Should boosters be real public figures by default, fictionalized, or a mix?
- Should boosters be controlled manually every day or optionally delegated to AI staff?
- How many debates should a default campaign include beyond English/French national debates?
- Should the daily newspaper use one neutral house style at first or multiple outlet voices from the start?
- Should articles expose exact causes of poll movement, or keep some uncertainty for realism?
- How much campaign finance detail is fun before it becomes accounting?
- Should regional offices be built manually or generated automatically from strategy choices?
- Should voter blocs be visible to the player directly or summarized through advisor reports?
- Should advance voting be shown as exact banked votes or an uncertain estimate?
- How detailed should post-election government formation be in the first full version?

## Recommended Next Step

Start with Phase 1 and Phase 2 together:

1. Create the Laravel 9 app skeleton in `electiongame` for PHP 8.1.2 and SQLite.
2. Add parties, leaders, boosters, issues, and 20 sample ridings.
3. Build the generator and the riding detail screen.
4. Add issue bars and initial support calculation.
5. Run a 45-day campaign in the backend and inspect daily snapshots.

This gives us a working core loop before we spend too much time on the full riding map.