feat(detail): show pupil gender split on school detail pages

Upgrades the existing "Pupils" stat to include a compact split bar and
percentage hint for mixed schools (single-sex schools already carry a
"Boys's/Girls's school" badge, so the split would be redundant).

Wires fact_pupil_characteristics into the API: new SQLAlchemy model and
a real census block in /api/schools/{urn} replacing the prior null stub.

On the primary detail page the inline "Pupils: 241" text is replaced by
a richer block (display number + bar + "52% girls · 48% boys"). On the
secondary detail page the existing "Total pupils" hero stat card grows
the bar and hint beneath the number. Both fall back to the previous
text-only rendering when census gender data is missing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend/data_loader.py

@@ -15,7 +15,7 @@ from .database import SessionLocal, engine
 from .models import (
     DimSchool, DimLocation, KS2Performance,
     FactOfstedInspection, FactParentView, FactAdmissions,
-    FactDeprivation, FactFinance,
+    FactDeprivation, FactFinance, FactPupilCharacteristics,
 )
 from .schemas import SCHOOL_TYPE_MAP
 
@@ -462,8 +462,20 @@ def get_supplementary_data(db: Session, urn: int) -> dict:
         else None
     )
 
-    # Census (fact_pupil_characteristics — minimal until census columns are verified)
+    # Census (latest year of fact_pupil_characteristics)
-    result["census"] = None
+    pc = safe_query(FactPupilCharacteristics, "urn", "year")
+    result["census"] = (
+        {
+            "year": pc.year,
+            "total_pupils": pc.total_pupils,
+            "female_pupils": pc.female_pupils,
+            "male_pupils": pc.male_pupils,
+            "fsm_pct": pc.fsm_pct,
+            "eal_pct": pc.eal_pct,
+        }
+        if pc
+        else None
+    )
 
     # Admissions (latest year)
     a = safe_query(FactAdmissions, "urn", "year")

backend/models.py

@@ -189,6 +189,24 @@ class FactAdmissions(Base):
     admissions_policy = Column(String(100))
 
 
+class FactPupilCharacteristics(Base):
+    """School pupil composition from EES census — one row per URN per year."""
+    __tablename__ = "fact_pupil_characteristics"
+    __table_args__ = (
+        Index("ix_pupil_chars_urn_year", "urn", "year"),
+        MARTS,
+    )
+
+    urn = Column(Integer, primary_key=True)
+    year = Column(Integer, primary_key=True)
+    phase_type_grouping = Column(String(50))
+    total_pupils = Column(Integer)
+    female_pupils = Column(Integer)
+    male_pupils = Column(Integer)
+    fsm_pct = Column(Float)
+    eal_pct = Column(Float)
+
+
 class FactDeprivation(Base):
     """IDACI deprivation index — one row per URN."""
     __tablename__ = "fact_deprivation"

nextjs-app/components/SchoolDetailView.module.css

@@ -83,6 +83,95 @@
     text-decoration: underline;
 }
 
+/* Pupils block — the "Pupils: N" inline text is upgraded to a richer
+   display whenever we have census gender data and the school is Mixed. */
+.pupilsBlock {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.7rem;
+    padding: 0.3rem 0.65rem 0.3rem 0.4rem;
+    background: rgba(243, 237, 228, 0.5);
+    border-radius: 10px;
+}
+
+.pupilsFigure {
+    font-family: var(--font-playfair), 'Playfair Display', serif;
+    font-size: 1.6rem;
+    font-weight: 700;
+    line-height: 1;
+    letter-spacing: -0.01em;
+    color: var(--text-primary, #1a1612);
+}
+
+.pupilsInfo {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    min-width: 140px;
+}
+
+.pupilsLegend {
+    font-size: 0.72rem;
+    color: var(--text-muted, #6d685f);
+    font-weight: 500;
+    line-height: 1;
+}
+
+.pupilsCapacity {
+    color: var(--text-muted, #6d685f);
+}
+
+.pupilsSplitRow {
+    display: flex;
+    align-items: baseline;
+    gap: 0.35rem;
+    font-size: 0.75rem;
+    font-weight: 600;
+    line-height: 1;
+}
+
+.pupilsSplitGirls {
+    color: #b45778;
+}
+
+.pupilsSplitBoys {
+    color: var(--accent-teal, #2d7d7d);
+}
+
+.pupilsSplitSep {
+    color: var(--border-color, #e5dfd5);
+    font-weight: 400;
+}
+
+.pupilsBar {
+    display: flex;
+    height: 4px;
+    border-radius: 999px;
+    overflow: hidden;
+    background: var(--border-color, #e5dfd5);
+    width: 100%;
+    min-width: 140px;
+}
+
+.pupilsBarGirls {
+    background: #b45778;
+}
+
+.pupilsBarBoys {
+    background: var(--accent-teal, #2d7d7d);
+}
+
+@media (max-width: 640px) {
+    .pupilsBlock {
+        display: flex;
+        width: 100%;
+    }
+    .pupilsInfo {
+        flex: 1;
+        min-width: 0;
+    }
+}
+
 .actions {
     display: flex;
     gap: 0.5rem;

nextjs-app/components/SchoolDetailView.tsx

@@ -235,12 +235,56 @@ export function SchoolDetailView({
                   </a>
                 </span>
               )}
-              {latestResults?.total_pupils != null && (
+              {(() => {
+                const censusTotal = census?.total_pupils ?? null;
+                const female = census?.female_pupils ?? null;
+                const male = census?.male_pupils ?? null;
+                const total = censusTotal ?? latestResults?.total_pupils ?? null;
+                const isMixed = schoolInfo.gender === 'Mixed' || schoolInfo.gender == null;
+                const hasSplit = isMixed && female != null && male != null && female + male > 0;
+
+                if (hasSplit && total != null) {
+                  const sum = female! + male!;
+                  const girlsPct = Math.round((female! / sum) * 100);
+                  const boysPct = 100 - girlsPct;
+                  return (
+                    <div className={styles.pupilsBlock}>
+                      <div className={styles.pupilsFigure}>{total.toLocaleString()}</div>
+                      <div className={styles.pupilsInfo}>
+                        <div className={styles.pupilsLegend}>
+                          pupils
+                          {schoolInfo.capacity != null && (
+                            <span className={styles.pupilsCapacity}> · capacity {schoolInfo.capacity.toLocaleString()}</span>
+                          )}
+                        </div>
+                        <div className={styles.pupilsSplitRow}>
+                          <span className={styles.pupilsSplitGirls}>{girlsPct}% girls</span>
+                          <span className={styles.pupilsSplitSep}>·</span>
+                          <span className={styles.pupilsSplitBoys}>{boysPct}% boys</span>
+                        </div>
+                        <div
+                          className={styles.pupilsBar}
+                          role="img"
+                          aria-label={`Gender split: ${girlsPct}% girls, ${boysPct}% boys`}
+                        >
+                          <span className={styles.pupilsBarGirls} style={{ width: `${girlsPct}%` }} />
+                          <span className={styles.pupilsBarBoys} style={{ width: `${boysPct}%` }} />
+                        </div>
+                      </div>
+                    </div>
+                  );
+                }
+
+                if (total != null) {
+                  return (
                     <span className={styles.headerDetail}>
-                  <strong>Pupils:</strong> {latestResults.total_pupils.toLocaleString()}
+                      <strong>Pupils:</strong> {total.toLocaleString()}
                       {schoolInfo.capacity != null && ` (capacity: ${schoolInfo.capacity})`}
                     </span>
-              )}
+                  );
+                }
+                return null;
+              })()}
               {schoolInfo.trust_name && (
                 <span className={styles.headerDetail}>
                   Part of <strong>{schoolInfo.trust_name}</strong>

nextjs-app/components/SecondarySchoolDetailView.module.css

@@ -884,6 +884,45 @@
     margin-top: 0;
 }
 
+/* Gender split — attached beneath the Total pupils stat value */
+.genderBar {
+    display: flex;
+    height: 4px;
+    border-radius: 999px;
+    overflow: hidden;
+    background: rgba(0, 0, 0, 0.08);
+    margin-top: 0.45rem;
+}
+
+.genderBarGirls {
+    background: #b45778;
+}
+
+.genderBarBoys {
+    background: var(--accent-teal, #2d7d7d);
+}
+
+.genderSplitHint {
+    font-size: 0.7rem;
+    color: var(--text-muted, #6d685f);
+    margin-top: 0.35rem;
+    font-weight: 500;
+}
+
+.genderSplitGirls {
+    color: #b45778;
+    font-weight: 600;
+}
+
+.genderSplitBoys {
+    color: var(--accent-teal, #2d7d7d);
+    font-weight: 600;
+}
+
+.genderSplitSep {
+    color: var(--border-color, #e5dfd5);
+}
+
 /* ── Attainment 8 visual bar ─────────────────────────── */
 .att8Viz {
     margin: 1.25rem 0 0.5rem;

nextjs-app/components/SecondarySchoolDetailView.tsx

@@ -70,7 +70,7 @@ interface SecondarySchoolDetailViewProps {
 
 export function SecondarySchoolDetailView({
   schoolInfo, yearlyData,
-  ofsted, parentView, admissions, senDetail, deprivation, finance, absenceData,
+  ofsted, parentView, census, admissions, senDetail, deprivation, finance, absenceData,
 }: SecondarySchoolDetailViewProps) {
   const router = useRouter();
   const { addSchool, removeSchool, isSelected } = useComparison();
@@ -793,15 +793,43 @@ export function SecondarySchoolDetailView({
                     <div className={styles.heroStatHint}>Education, Health and Care Plan</div>
                   </div>
                 )}
-                {(schoolInfo.total_pupils != null || latestResults?.total_pupils != null) && (
+                {(() => {
+                  const total = census?.total_pupils ?? schoolInfo.total_pupils ?? latestResults?.total_pupils ?? null;
+                  if (total == null) return null;
+                  const female = census?.female_pupils ?? null;
+                  const male = census?.male_pupils ?? null;
+                  const isMixed = schoolInfo.gender === 'Mixed' || schoolInfo.gender == null;
+                  const hasSplit = isMixed && female != null && male != null && female + male > 0;
+                  const sum = hasSplit ? female! + male! : 0;
+                  const girlsPct = hasSplit ? Math.round((female! / sum) * 100) : 0;
+                  const boysPct = hasSplit ? 100 - girlsPct : 0;
+                  return (
                     <div className={styles.heroStatCard}>
                       <div className={styles.heroStatLabel}>Total pupils</div>
-                    <div className={styles.heroStatValue}>{(schoolInfo.total_pupils ?? latestResults!.total_pupils!).toLocaleString()}</div>
+                      <div className={styles.heroStatValue}>{total.toLocaleString()}</div>
-                    {schoolInfo.capacity != null && (
+                      {hasSplit && (
+                        <>
+                          <div
+                            className={styles.genderBar}
+                            role="img"
+                            aria-label={`Gender split: ${girlsPct}% girls, ${boysPct}% boys`}
+                          >
+                            <span className={styles.genderBarGirls} style={{ width: `${girlsPct}%` }} />
+                            <span className={styles.genderBarBoys} style={{ width: `${boysPct}%` }} />
+                          </div>
+                          <div className={styles.genderSplitHint}>
+                            <span className={styles.genderSplitGirls}>{girlsPct}% girls</span>
+                            <span className={styles.genderSplitSep}> · </span>
+                            <span className={styles.genderSplitBoys}>{boysPct}% boys</span>
+                          </div>
+                        </>
+                      )}
+                      {schoolInfo.capacity != null && !hasSplit && (
                         <div className={styles.heroStatHint}>Capacity: {schoolInfo.capacity}</div>
                       )}
                     </div>
-                )}
+                  );
+                })()}
               </div>
             </>
           )}

nextjs-app/lib/types.ts

@@ -120,12 +120,17 @@ export interface OfstedParentView {
 
 export interface SchoolCensus {
   year: number;
-  class_size_avg: number | null;
+  total_pupils: number | null;
-  ethnicity_white_pct: number | null;
+  female_pupils: number | null;
-  ethnicity_asian_pct: number | null;
+  male_pupils: number | null;
-  ethnicity_black_pct: number | null;
+  fsm_pct: number | null;
-  ethnicity_mixed_pct: number | null;
+  eal_pct: number | null;
-  ethnicity_other_pct: number | null;
+  class_size_avg?: number | null;
+  ethnicity_white_pct?: number | null;
+  ethnicity_asian_pct?: number | null;
+  ethnicity_black_pct?: number | null;
+  ethnicity_mixed_pct?: number | null;
+  ethnicity_other_pct?: number | null;
 }
 
 export interface SchoolAdmissions {