Shared shell

Sidebar, org modal, top bar, search, alerts, copilot.

Shared shell

The shell is everything that stays on screen while you change pages: sidebar, top bar, search, alerts, copilot, account menu, and the organization modal.

Sidebar

Zone labels from NAVIGATION_ZONES, plus an ADMIN block for institution admins:

• WORK — what you are actively working: pipeline, dossiers, mandates, portfolio.
• ANALYSIS — engines applied to that work: curves, financial statements, covenants, stress lab, rules.
• MONITORING — early signals, auction calendars, maturities.
• KNOWLEDGE — comparables, research, precedents, memos.
• ADMIN — Membres & droits (/workspace/org-members): invite members, assign institutional roles, view the derived module matrix, set sparse overrides, read the membership audit log. Access is gated to institution admins (and the local administrator profile role).

Badges on the sidebar are computed from the open deal:

• Exhaustivité shows the count of fatal blockers (missing documents that stop a closing).
• Risk shows the count of risks whose severity is CRITICAL or HIGH.
• Contradictions shows contradiction_alerts.length.

The footer shows CEMAC ISO 9001:2015, a link Portail to /landing, and Packs (n), which opens the organization modal. ISO 9001 is a quality-management standard. Here it is a label for the audit trail the product claims to keep, not a certification check the code performs.

Clicking the organization name opens Profil Institutionnel & Éditions Métier.

Organization modal

Three tabs:

1. Choix de l’Édition — pick a business preset. The card shows the edition name, tagline, the core question, the north-star KPI, how many modules are recommended, and the intelligence packs. Choosing an edition replaces the module checklist with that preset’s recommended modules. It is not saved until you press Appliquer la configuration.
2. Modules & Packs Actifs — toggle the 13 analysis modules and a filter Filtre Édition Actif / Afficher Tous les Modules. The filter is stored as filterByEdition. The note on this tab says the shared engine still runs accounting identities and major legal risks even if a module is hidden.
3. Institution & Juridiction — organization name and primary CEMAC country (CG, GA, CM, TD, CF, GQ). The country chooses the default national tax code in the regulatory story (CGI Congo or CGI Gabon) and the treasury the desk treats as home. Badges for OHADA, BEAC, COSUMAF, and COBAC are display-only.

Organization profile is loaded from the SoR on workspace SSR (getOrganizationProfile). If the SoR is unreachable, the UI shows an empty institution shell — never a branded demo firm. Edition, modules, and jurisdiction come from the authenticated organization record.

Roles are not editable in this modal. The signed-in role comes from the stored profile (administrator by default).

Top bar

Control	What it does	Where the data comes from
Skip link Aller à l'espace d'analyse	Jumps to the page body	—
Search Rechercher émetteurs, deals, documents, obligations... and ⌘K	Opens global search	A fixed list of 22 rows, not the live deals
Status badge	Shows status_label of the open deal	The deal. Tone: active = success, structuring = info, committee = warning
Compte	Account menu	Organization profile
Lancer l’analyse	POST /api/pipeline. While running, the label is Calcul…	Drawer title: deterministic Python pipeline (Nelson-Siegel and SYSCOHADA). Badges: En cours…, Succès, Erreur
Copilot	Opens the copilot sheet	The open deal
Alerts bell	Opens the alerts center	The red dot is computed (fatal blockers or any contradiction). The six cards inside are a fixed list
Afficher les sources / Masquer les sources	Toggles the PDF viewer for the selected deal document	The open deal’s data room, on deal-workspace sections

Deal-workspace sections (the ones that show the status badge and the sources toggle) are: data room, completeness, Q&A, financials, ratios, credit lab, review grids, contradictions, regulatory, deal graph, diligence runner, risk register, and memo.

Global search

Search hits come from tenant-scoped Postgres SearchDocuments via /api/locus/search (french tsvector/GIN), plus the institution’s authorized deal list. A fresh organization with no dossiers and no indexed documents sees an empty result set — there is no static CEMAC catalog in the product path.

Pills: Tout, Émetteurs, Deals, Instruments, Documents, Réglementation, Recherche, Mémoire.

Clicking a deal row navigates with the SoR deal_* id. Legacy aliases (e.g. proj_*) still resolve on the BFF for bookmarks, but new work should use canonical ids.

Alerts center

Title: Centre d’Alertes & Risques Institutionnels. Alerts load from SoR GET /api/locus/alerts. A fresh tenant has zero alerts until analysis/OCR writers emit them — the API never auto-seeds demo cards.

After dossier OCR + analysis, SoR writers create AlertItems from: open contradictions (CRITICAL/MAJOR), covenant breaches on RatioSnapshots, and fatal open Blockers. Severity badges: DIRIMANT, ATTENTION, MARCHÉ (when market ingest has written rows).

Lifecycle actions (assign / acknowledge / archive) remain on the same BFF routes and audit chain.

You will meet these alerts again as the running example. The short version, in developer language:

• DSCR (debt service coverage ratio) asks “does cash available this year cover the loan payments due this year?” Below 1.0x means the cash does not cover the payments. A contract often requires something like 1.20x, meaning 20% spare cash.
• A basis point (bp) is 0.01 percentage point. 45 bp is 0.45%. 100 bp is 1%.
• A term sheet is the short commercial summary of a loan (amount, margin, maturity, covenants). The loan agreement is the long contract. If they disagree, somebody has to say which one wins before the committee.
• A concession is a state contract that lets a company run a public service (here, water and electricity) until a date. If the bond is still outstanding after the concession ends, the company may no longer own the assets that were supposed to repay the bond.
• Article 42 of the BEAC foreign-exchange regulation requires a cross-border loan to be declared to the central bank.

Copilot (Assistant d’analyse)

Opened from the navbar (no floating FAB). Sheet title Instruction (eyebrow Assistant d'analyse · Préparatoire). Every reply is framed as preparatory analysis, not a regulator’s decision, and carries a COSUMAF / legal disclaimer.

Architecture and Layers:

1. Agentic Tool Orchestrator & Registry (copilot/agent.ts, copilot/tools/registry.ts, financials.ts) — agentic dispatcher with 16 certified deterministic tools:
   • Credit & Financials: get_syscohada_ratios (Net Debt, EBE, DSCR, ICR, cash), simulate_credit_stress (EBE shocks -10%, -20%, -30% with scenario comparison card), audit_covenants (contract ceilings and headroom). Fail closed if periods are missing (no invented constants).
   • BlackRock Aladdin Fixed Income & Relative Value: price_fixed_income_instrument (clean/dirty price, duration, convexity, DV01 sensitivity under +50 bp shock), compare_bond_to_curve (corporate yield vs Nelson-Siegel sovereign curve to compute sovereign credit spread in bps).
   • BlackRock Aladdin Portfolio Intelligence: get_portfolio_exposure (market value in XAF, book duration, DV01, top issuers), run_portfolio_stress (+50, +100, +150 bps parallel shifts with P&L and DV01 loss approximation), explain_portfolio_duration (OTA vs BTA factor decomposition), list_portfolio_exceptions (open limit breaches).
   • Diligence & Regulatory: audit_contradictions_radar (dual-citations), explain_concession_maturity_trap (2028 Concession vs 2031 Debt 35-month gap), get_risk_register, audit_dataroom_completeness (fatal blockers like Quitus Fiscal DGI and BEAC Art. 42 declaration), check_regulatory_compliance (OHADA AUS Art. 140 escrow pledge, BEAC R-2018/02, COSUMAF visa), compile_credit_memo, and investigate_360.
2. Multi-Turn Conversation Memory (copilot/agent.ts, IntelligenceCopilot.tsx) — passes prior conversation history (history: CopilotMessage[]) on every call. Resolves contextual follow-ups ("Et si l'EBITDA baisse de 15% ?", "Quelle est la marge sur ce covenant ?") seamlessly.
3. Retrieval (copilot/async.ts, retrieval.ts) — for ask / investigate / review / draft, calls GET /api/locus/search (Postgres SearchDocuments, including OCR pages) and merges spatial citations with bounding boxes. GET /api/locus/blockers enriches missing-piece answers.
4. Optional LLM prose (copilot/llm.ts) — only for draft / investigate, only if COPILOT_LLM_PROVIDER is openai or anthropic. Default off. The model may rephrase French; it must not invent numbers.

Workbench passes organizationId on every call for tenant checks.

Scope (Périmètre d'analyse): current page (prefer active doc), whole dossier (default), whole data room, or CEMAC corpus (blocks deal financial calculations).

Mode strip: Question, Calcul, Investigation, Revue, Rédaction. Keywords can overwrite the selected mode.

Command	Intent
/calculate	Formal ratios from live periods or fixed income bond pricing
/investigate	360° synthesis (ratios + alerts + risks + dataroom)
/compare	Structured contradiction_alerts or sovereign curve spread analysis
/stresstest	Shock EBE / leverage on live periods or portfolio yield shock
/review	Covenant / clause review mode
/risks	Top risks from the risk register
/draft	Memo sections from project.memo (+ optional LLM polish)
/portfolio	Book exposure, rate stress, exceptions, duration explainer
/blockers	Completeness + Postgres blockers

Evidence marks: Vérifié, Calculé, À examiner, Preuve insuffisante. Live Moteurs : badges display certified algorithms executed (e.g. [✓ LEVIER DETTE NETTE / EBE · 2.52x]). Blocks order Source → Calcul → Interprétation, then citations, actions, follow-ups. A scenario card shows metric, cap, audited base, after-shock value, and residual headroom.

explain() from a ratio, risk, or contradiction opens this sheet and sends that string as the user message. Empty-state suggestions depend on the active tab (portfolio, instruments, sovereign-curves, etc.).

Account menu

Profil goes to /workspace/profile. Déconnexion posts action=logout to /api/auth (revokes SoR AuthSessions and clears the signed cookie) and returns to /. The name and role shown come from the authenticated institutional session.

Pipeline button

Lancer l’analyse posts to /api/pipeline and names the open borrower in the log. The drawer is titled as a deterministic Python run of the Nelson-Siegel curve fit and the SYSCOHADA statements. Treat it as a job launcher attached to the shell, not as a page.

---