| name | topfinance-uk-codebase-map |
| description | TopFinance UK repository operating map for safe implementation work. Use when modifying uk-topfinanzas-com architecture, routes, APIs, SEO, analytics, ads, content listings, env config, deployment scripts, or when coordinating parity with topnetworks-sync-orchestrator across TopNetworks properties. |
TopFinance UK Codebase Map
This skill is the implementation-oriented operating map for the TopFinance UK repository:
- Repo: /Users/macbookpro/GitHub/uk-topfinanzas-com
- Domain: https://uk.topfinanzas.com
- Market: United Kingdom (en-GB, GBP, FCA context)
- Runtime port: 3004
Use this skill to navigate, modify, and extend the system without rediscovering architecture, invariants, and operational workflows.
Relationship to TopNetworks Orchestrator
This skill is repository-local. It is governed by the cross-repo orchestrator skill:
- /Users/macbookpro/GitHub/.agents/skills/topnetworks-sync-orchestrator/SKILL.md
Coordination contract:
- Use this skill for UK-local implementation detail and safe editing.
- Use the orchestrator skill for cross-repo parity work across US/UK/MX/BudgetBee.
- Before propagating shared changes, classify scope using orchestrator taxonomy:
- shared architecture
- market-localized
- brand-localized
- repo-specific
- Preserve UK adaptations when syncing:
- Canonical domain: uk.topfinanzas.com
- Locale: en-GB
- Currency: GBP
- FCA-compliant language and representative APR conventions
- Do not commit/push/deploy during sync tasks unless explicitly requested.
Repository bridge files:
- docs/TOPNETWORKS_SYNC_WORKFLOW.md
- scripts/topnetworks-predeploy.mjs (wrapper around orchestrator deploy preflight for repoId topfinanzas-uk)
Company and Portfolio Context (TopNetworks)
Source context comes from:
- TOPNETWORKS_COMPANY_PROFILE.md (UK-adapted company profile)
- /Users/macbookpro/GitHub/TopNetworks-Inc.md (parent company profile)
Key operational model to preserve:
- Performance publishing + traffic arbitrage economics (spread = revenue/session - cost/session)
- Multi-market portfolio (US, UK, MX, LatAm, brand variants)
- Stacked monetization: affiliate/CPA + ad-tech layers (AdZep, TopAds, System1 where applicable)
- Analytics and attribution continuity are business-critical
System Boundaries and Purpose
TopFinance UK is a Next.js App Router financial comparison property for UK consumers with:
- Financial solutions pages (credit cards and loans)
- Personal finance editorial content
- Quiz/recommender flows
- Lead capture and subscription APIs
- SEO and structured data support
- GTM + ad stack integration
Out of scope for this repo skill:
- Non-UK brand assets/voice from sibling properties
- Cross-repo rollouts (handled by orchestrator)
- Production server operations beyond documented scripts
High-Signal Architecture Map
Application shell and rendering
- app/layout.tsx
- app/page.tsx + app/page-client.tsx
- middleware.ts
Observed implementation specifics:
- App Router with server metadata + client page components.
- GTM snippet is hardcoded in head/body (container GTM-MR76NXR3).
- Local Poppins font via next/font/local.
- Critical CSS is inlined from app/critical.css at runtime.
- Global providers include NavigationProvider and analytics helpers.
- AdZep feature flag currently hard-disabled in layout via ENABLE_ADZEP = false.
Route families
- app/financial-solutions/** (product and requirements pages)
- app/personal-finance/**
- app/blog/**
- app/credit-card-recommender-p1, p2, p3
- app/quiz, app/quiz-2 (legacy/restricted)
SEO and schema system
- lib/seo.ts
- lib/seo-route-registry.ts
- components/seo/json-ld.tsx
- app/sitemap.ts
- app/robots.ts
Observed specifics:
- Canonical base URL is https://uk.topfinanzas.com.
- Route metadata is generated from registry entries; unknown routes infer fallback metadata.
- Sitemap is built from getIndexableRoutes() and route categories.
- Robots disallow recommender/quiz/testing paths and allow major crawlers/AI crawlers.
- Middleware injects hreflang Link headers per request.
Ads and analytics layers
- components/analytics/**
- lib/ads/**
- components/ads/**
Observed specifics:
- GTM and Google ad components load in layout.
- AdZep code path exists with SPA bridge and retry logic, but master enable switch is off in layout.
- Ad unit/container detection and excluded path logic are in lib/ads/config.ts and lib/ads/activate-adzep.ts.
- UTM persistence/injection flows are active in layout.
API surface and integration points
- app/api/sheets/route.ts (Google Sheets write/upsert-like append with duplicate check)
- app/api/subscribe/route.ts (Brevo + ConvertKit dual write)
- app/api/contact/route.ts (Brevo contact + optional note)
- app/api/search/route.ts (Vertex AI Search)
- app/api/authors/route.ts (authors JSON)
- app/api/posts/route.ts (currently debug-oriented metadata existence scanner)
- app/api/webmanifest/route.ts (fallback manifest endpoint)
Operational scripts
- scripts/git-workflow.sh
- scripts/deploy_update.sh
- scripts/sync-branches.sh
- scripts/topnetworks-predeploy.mjs
- scripts/test-brevo*.js
Data and Content Flow Map
Lead capture and attribution
- Client forms capture personal + UTM context.
- UTM normalizers persist attribution values (utm_* plus source/medium/campaign aliases).
- APIs enrich payloads with static market-brand fields:
- Pais: Reino Unido
- Marca: Top Finanzas
- Data sinks:
- Google Sheets (quiz/registration telemetry)
- Brevo (contact/subscription)
- ConvertKit (parallel subscription path)
Content discovery and listing
Important implementation detail:
- Many listing pages are manually curated with hardcoded allPosts arrays in page-client files.
- This means adding/removing articles requires multi-file updates, not only creating route content.
Primary listing locations to verify after content edits:
- app/page-client.tsx
- app/blog/page-client.tsx
- app/personal-finance/page-client.tsx
- app/financial-solutions/page-client.tsx (and related category clients where present)
- components/mdx/blog-layout.tsx (recent articles/sidebar links)
Financial solutions SEO content model
- Each product family typically has paired pages:
- benefits/product page
- requirements page
- SEO registry entries should include both routes for metadata and sitemap correctness.
Environment and Runtime Configuration
Primary runtime config files:
- package.json
- next.config.mjs
- tsconfig.json
- tailwind.config.js
Relevant environment variables observed in code:
- GOOGLE_SERVICE_ACCOUNT_EMAIL (required for sheets endpoint)
- GOOGLE_PRIVATE_KEY (required; newline normalization handled)
- GOOGLE_SHEET_ID (required for sheets endpoint)
- BREVO_API_KEY (required for contact/subscribe)
- KIT_API_KEY (required for ConvertKit write path)
- KIT_API_URL (optional override for ConvertKit endpoint)
- VERTEX_AI_SEARCH_API_KEY (required for /api/search)
- NEXT_PUBLIC_ENABLE_LOGGING (optional logger override in production)
Additional env vars are referenced in project docs (for email and operational flows):
- SENDGRID_API_KEY
- SENDER_EMAIL
- RECIPIENT_EMAIL
Build, Validation, and Deployment Workflow
Local development:
- pnpm dev (port 3004)
- pnpm build
- pnpm start (port 3004)
- pnpm lint
- pnpm format
Brevo integration tests:
- pnpm test:brevo
- pnpm test:brevo-direct
- pnpm test:brevo-api
Git/deploy process in this repo:
- Commit message is expected in lib/documents/commit-message.txt.
- scripts/git-workflow.sh automates add/commit/push on dev, then optional merge to main/backup.
- scripts/deploy_update.sh is server-oriented and deploys from main using pnpm build + pm2 restart.
TopNetworks synchronized preflight:
- scripts/topnetworks-predeploy.mjs preflight --dry-run
Non-Negotiable Guardrails
- Keep UK localization consistent:
- en-GB copy and metadata
- GBP references
- FCA-aware regulatory language
- Preserve GTM placement and container correctness in app/layout.tsx:
- hardcoded GTM script + noscript pattern
- dataLayer naming consistency
- Do not break recommender lock routing behavior:
- cookie/localStorage lock contract in lib/navigation/recommender-lock.ts
- redirect behavior in middleware.ts for /quiz and /quiz-2 when lock exists
- Maintain SEO integrity:
- update lib/seo-route-registry.ts when creating/removing meaningful pages
- verify sitemap/robots implications
- Preserve listing parity for editorial changes:
- update all relevant allPosts arrays and sidebar recent links
- do not assume dynamic CMS indexing currently powers listings
- Financial solutions layout standard is mandatory:
- follow .github/instructions/FINANCIAL_SOLUTIONS_LAYOUT_STANDARD.instructions.md
- preserve ad slots and required element order
- Do not bypass orchestrator process for cross-repo propagation.
Common Change Recipes
Recipe: Add a new UK financial solution page pair
- Create benefits and requirements route pages under app/financial-solutions/.
- Follow required layout standard and ad slot placement.
- Add/verify SEO registry entries in lib/seo-route-registry.ts for both routes.
- Update category/listing allPosts arrays and any sidebar references.
- Validate metadata, sitemap, and internal links.
Recipe: Add a new personal finance article route
- Add new route page under app/personal-finance//.
- Register/verify SEO metadata coverage.
- Update all listing arrays (home, blog, personal finance).
- Update sidebar recent article links if needed.
- Validate robots/sitemap behavior and canonical domain.
Recipe: Extend lead form payload fields
- Update frontend form payload shape.
- Update app/api/sheets/route.ts mapping and headers if needed.
- Update app/api/subscribe/route.ts and app/api/contact/route.ts mapping.
- Preserve UTM alias handling and brand static fields.
- Test with pnpm test:brevo and manual form submission.
Recipe: Modify ad/analytics behavior safely
- Check app/layout.tsx global switches and script placement.
- If touching AdZep behavior, verify lib/ads/config.ts and lib/ads/activate-adzep.ts assumptions.
- Keep excluded paths and article-path logic intact unless explicitly changing policy.
- Validate no regressions in UTM persistence/injection.
Recipe: Cross-repo shared refactor (US/UK/MX/BudgetBee)
- Pause and invoke topnetworks-sync-orchestrator skill.
- Build a propagation matrix with localized adaptations.
- Apply changes with UK constraints preserved.
- Run orchestrator parity/validate commands before merge/deploy operations.
Decision Matrix: Local vs Orchestrated Work
Use this repo skill only when:
- the change is UK-only
- implementation detail is specific to uk-topfinanzas-com
- no parity requirement exists across sibling repos
Use orchestrator when:
- shared components, SEO policies, analytics patterns, docs, or scripts should converge across properties
- parity audits are requested
- synchronized rollout is required
Quick File Entry Points by Task
- App shell/global scripts: app/layout.tsx
- Route guard and hreflang headering: middleware.ts
- SEO route metadata: lib/seo.ts + lib/seo-route-registry.ts
- Sitemap/robots: app/sitemap.ts + app/robots.ts
- Lead ingestion: app/api/sheets/route.ts
- Subscriptions: app/api/subscribe/route.ts
- Contact pipeline: app/api/contact/route.ts
- Search endpoint: app/api/search/route.ts
- Brand constants: lib/constants.ts
- Logger strategy: lib/logger.ts
- AdZep runtime internals: components/analytics/adzep-spa-bridge.tsx + lib/ads/*
- Sync workflow handoff: docs/TOPNETWORKS_SYNC_WORKFLOW.md + scripts/topnetworks-predeploy.mjs
Completion Checklist for Agents
Before finishing significant work, verify:
- Correct UK localization/compliance language
- No broken route-level metadata behavior
- Listing arrays updated where content changed
- API payload mappings consistent across sinks
- No accidental GTM/ad stack contract break
- Orchestrator handoff documented if the change has cross-repo impact
If the task potentially affects sibling properties, explicitly recommend invoking topnetworks-sync-orchestrator next.
