myTrajectoryTechnical Reference

This page covers the technical detail behind myTrajectory as implemented in the current codebase: architecture layers, the full tech stack, data model, Cloud Functions, security patterns, the design system, and testing approach. The platform is currently in live testing with two charity partners, with the recruiter-facing layer in active discussion with recruitment professionals. For the product thinking and design rationale, start with the narrative.

System Overview

The application is built as a layered architecture with clear separation between client, server, AI, and data concerns.

Tech Stack

Frontend & framework

Backend & infrastructure

AI providers

Quality & monitoring

Feature Landscape

myTrajectory spans several feature domains, with shared data and service layers connecting them.

4.1 Core workspace

4.2 AI-powered features

4.3 Relationship management

4.4 Advisor & collaboration

4.5 Public profiles & discovery

4.6 Onboarding & guidance

4.7 Platform & integration

AI Architecture

The AI subsystem is one of the most complex parts of the application. Rather than calling a single provider directly, the tested AI flow modules and several AI-backed routes use a configurable provider layer with intent-based model selection, cost tracking, and structured output validation.

Multi-provider gateway

Intent-based routing

Each AI flow declares an intent that determines which model class to use. Intents are extensible and the system is not limited to a fixed set. Examples include:

Routing configuration is stored in Firestore, enabling dynamic provider changes without deployment. Organisations can override system-wide routing with their own provider keys.

Structured output validation

JSON-structured AI outputs in the flow layer are validated against Zod schemas before they are used. This keeps the typed flow modules defensive when model output is non-deterministic.

// Example: STAR Answer Review output schema
const AIReviewSchema = z.object({
  overallGrade: z.enum(['Excellent', 'Good', 'Fair', 'Draft', 'Error']),
  specificity: z.number().min(1).max(5),
  impact: z.number().min(1).max(5),
  relevance: z.number().min(1).max(5),
  feedback: z.string(),
  sectionFeedback: z.record(SectionReviewSchema),
  followUpQuestions: z.array(z.string()).max(3),
  competencyTags: z.array(z.string()).max(5),
});

Token cost tracking

Every AI call records token usage. The platform calculates the real provider cost and applies a multiplier to cover infrastructure alongside AI spend. The resulting amount is deducted from the user’s credit balance in pence, with a ledger entry for every transaction.

Prompt system

Prompts live in src/ai/prompts/ as templates with variable substitution ({{{varName}}}). System instructions define tone rules, output structure, and guardrails. Some prompts embed example output blocks or strict JSON structure examples to keep responses consistent.

Real-time voice relay

The Story Companion uses a WebSocket-based live relay for real-time transcript streaming during voice conversations. This presents specific engineering challenges:

• Connection state management: the relay handles connect, disconnect, and reconnect states with automatic recovery
• Transcript windowing: long conversations accumulate context that exceeds model token limits. A rolling window utility builds reconnection context from the most relevant recent messages while truncating older content, maintaining conversational coherence without overflow
• Activity payloads: the relay streams structured activity data (not just raw text), enabling the AI to distinguish between user speech, system events, and its own prior responses

Candidate embeddings & vector search

Candidate summaries are embedded into vector representations stored in Firestore’s candidate_embeddings collection. Cloud Functions regenerate embeddings after Experience Record updates driven by CVs, STAR answers, and application materials. The admin candidate search uses Firestore’s findNearest() with cosine distance to find semantically similar candidates from job description text.

Credit & cost model

The platform has real running costs. Rather than a monthly subscription, users pay for credits, a model chosen because it is fairer: people pay in proportion to what they use, and charities can fund their own clients directly rather than managing seat licences.

The cost calculation is straightforward: every AI call records tokens in and out, the actual provider cost is calculated, and a platform multiplier is applied to cover infrastructure. Credits are tracked in pence (e.g. £5.00 = 500p) and deducted per use, with a full ledger of every transaction.

A small monthly minimum (~£2) is deducted from inactive accounts so unused balances don’t sit indefinitely. Accounts are never turned off. Without credit, AI-powered features become unavailable and the experience is effectively read-only.

Usage tracking is live; enforcement is the next commercial milestone.

Data Model

Firestore schema

Data is organised into root collections with user-scoped subcollections:

Experience Record hierarchy

Three-level structure: Node (role/education/skill) → Item (achievement/responsibility) → Variation (phrasing + source + context). Variations preserve how the same achievement has been described across CVs, STAR answers, cover letters, and voice sessions. See the narrative for the product rationale.

Sources feed in automatically via Cloud Functions:

Key domain types

The type system spans 45+ type files. Key domains include:

Advisor & Collaboration

The advisor system transforms myTrajectory from a solo tool into a collaborative platform. Advisors see a unified dashboard of their client roster with consent-gated access to detailed data.

Client roster

Each client card shows:

• Status indicators: active today, active this week, quiet, needs attention, consent pending/revoked
• Activity sparkline: 28-day visualisation of daily activity counts
• Quick metrics: current streak, recent application count
• Last activity: timestamp with sortable filtering

Consent model

Advisors can only view client data that the client has explicitly consented to share. Three granular scopes control access (see Trust & Collaboration for the design rationale):

Consent enforcement

Consent is enforced at the API route level, not the client. Every advisor-facing API route calls requireConsent(caller, targetUserId, scope) before returning data. A 5-minute in-memory cache (hasConsent()) balances freshness against Firestore read costs.

All consent changes are audit-logged with actor, action, and before/after state.

Pinned content & recommendations

Advisors can recommend specific resources, events, and content directly to individual clients. Pinned items appear on the client’s workspace hub alongside their own data, with status tracking (pending/done). This extends the advisor role from passive observer to active guide.

Connection summaries

To avoid expensive cross-user queries, Cloud Functions maintain denormalised ConnectionSummary documents that cache activity metrics, streak data, and sparkline arrays. Fields include lastActivityAt, activityCount7d, activityCountPrev7d, recentApplicationCount, currentStreak, and a weeklySparkline[] array. These update on every activity write via Firestore triggers, with a scheduled reconciliation job to correct any drift.

Activity Intelligence

The Activity Intelligence engine is a signal detection system that analyses recent behaviour across multiple rolling windows and surfaces actionable insights. It detects 13 distinct signals across momentum, gaps, and misalignment.

How it works

1. Gather: gatherSignalData fetches activity history, applications, STAR answers, focus sessions, and dismissed signals from Firestore.
2. Detect: detectActiveSignals is a pure function that evaluates all 13 signal conditions against the gathered data. No Firestore calls, fully testable.
3. Rank: signals are prioritised: problem signals outrank positive signals; re-engagement fires alone.
4. Display: ranked signals are shown to the user with contextual copy (different messaging when an advisor is present).
5. Dismiss: users can dismiss signals; dismissed signals have a 14-day cooldown before they can fire again.

Signal inventory

Engineering note: The signal detection function (detectActiveSignals) is deliberately pure: it takes data in and returns signals out. All Firestore interaction happens in the separate gatherSignalData function. This separation makes the detection logic fully unit-testable; the current service test file covers 13 signal conditions plus ranking, dismissal, snooze, and helper behaviour across 68 cases.

Security Patterns

Security is enforced at every layer, not assumed at any.

Authentication & authorisation

• Firebase JWT verification on every API route via requireVerifiedUser
• Custom claims synced via Cloud Functions on profile changes
• Role-based gates: standard, advisor, admin via requireRole
• Organisation boundary checks via requireOrgAccess and requireOrgMembership
• Consent verification with 5-minute cache via requireConsent
• Conversation access checks via requireConversationAccess

API route pattern

Many sensitive API routes follow a common defensive pattern built from authentication, validation, rate limiting, idempotency, and service-layer execution:

export async function POST(request: NextRequest) {
  // 1. Authenticate and authorise
  const user = await requireVerifiedUser(request);

  // 2. Validate request body against Zod schema
  const body = await validateBody(request, CreateApplicationSchema);

  // 3. Enforce rate limits
  await rateLimitOrThrow(user.uid, 'create-application');

  // 4. Check idempotency (prevent duplicate operations)
  await checkIdempotency(request, user.uid);

  // 5. Execute business logic via service layer
  const result = await applicationService.create(user.uid, body);

  // 6. Return typed response
  return NextResponse.json(result, { status: 201 });
}

Firestore rules

Security rules enforce access at the database level as a second line of defence:

• Visibility model: public, authenticated, organisation, private
• Helper functions: isOwner(), isAdvisor(), isAdmin(), canAdvisorReadActivity()
• Scope-checking functions for advisor access to client data
• Content creator checks and invited-user lists

Rate limiting

Token-bucket algorithm with Firestore-backed state and in-memory fallback. Per-user, per-feature granularity. Graceful degradation if Firestore is unavailable.

Data encryption

Sensitive fields (provider API keys, OAuth tokens) are encrypted at rest using AES-256-GCM via DATA_ENCRYPTION_KEY_CURRENT, with decryption fallback through DATA_ENCRYPTION_KEY_OLD_* during key rotation.

OAuth hardening

The email integration OAuth flow (Google and Microsoft) uses cryptographic state tokens to prevent CSRF attacks. Each authorisation request generates a 256-bit random state token stored in Firestore with a 10-minute TTL. On callback, the token is validated, checked for expiry, and immediately deleted to prevent replay. Callbacks that arrive without an email address from the provider are rejected outright.

Content Security Policy

A strict Content Security Policy controls which scripts, styles, connections, and frames the browser is allowed to load. The policy defaults to self for all resource types and explicitly allowlists only the external origins the platform depends on (Firebase, Google APIs, Sentry, and analytics). Plugins are disabled entirely, forms cannot submit to external sites, and the application cannot be iframed by third parties. Standard hardening headers (HSTS with preload, X-Content-Type-Options, X-Frame-Options, Referrer-Policy) are set alongside the CSP.

Idempotency

Request deduplication prevents double-deduction of credits and duplicate record creation. Crucial for unreliable network conditions and retry scenarios.

Feature flags

Environment-variable-based feature toggles control rollout of new capabilities (live voice relay, AI example finder, AI STAR review). A context provider and useFeatureFlag hook give components clean access to flag state. This enables gradual rollout and safe experimentation without deployment risk.

Request ID tracking

Every client request generates a unique ID via createClientRequestId() that is propagated through the server via getRequestIdFromRequest(). This correlates logs, errors, and metrics across client and server boundaries, making it possible to trace a single user action through the entire stack in Sentry and system logs.

Cloud Functions

Cloud Functions handle asynchronous processing that should not block user interactions. They fall into two categories: Firestore triggers (react to data changes) and scheduled jobs (run on a cadence).

Firestore triggers

Scheduled jobs

Domain event bus

Firestore triggers handle data-level reactions, but some actions need coordination across multiple concerns at once: logging an activity, creating an in-app notification, and sending an email should all happen when an advisor is assigned, but none of them belongs inside the trigger itself. A domain event bus handles this by decoupling the action from its consequences.

When a meaningful action occurs, the originating code publishes a single domain event. Registered subscribers (currently an event store, an activity logger, a notification writer, and an email sender) each decide independently whether to act on it. Subscribers declare themselves as either critical (failure rolls back the publish) or best-effort (failure is logged but does not block). The email subscriber, for example, runs as best-effort: a failed email should never prevent an advisor assignment from completing.

Because the same HTTP request can be retried, the bus supports subscriber-level idempotency. Each event generates a deterministic document ID from its type, entity, and request ID. Before a subscriber executes, the bus checks whether that subscriber has already processed the event. This prevents duplicate emails and duplicate activity entries without requiring callers to manage deduplication themselves.

Transactional email

Outbound email is handled by Resend, triggered via the email subscriber on the domain event bus. Events such as advisor assignment, consent changes, resource recommendations, event invitations, and new messages each produce a corresponding email to the affected party. Multi-recipient events are sent in parallel using Promise.allSettled() so that one failed delivery does not block the rest.

Users control what they receive through a two-level preference model: a global kill switch and per-type opt-outs stored on the user profile. New accounts start with all notifications enabled. The preference check is fail-open: if the Firestore lookup fails, the email is sent rather than silently dropped, on the basis that a duplicate is less harmful than a missing notification.

Every email includes List-Unsubscribe and List-Unsubscribe-Post headers conforming to RFC 8058, enabling one-click unsubscribe in supporting mail clients. Delivery outcomes are written to system_logs for admin visibility.

Design System

Component architecture

The UI is built on a three-layer component architecture:

Component inventory

The shared UI layer currently contains 56 component files in src/components/ui, while generated design-system stats track 34 audited shared/domain components used across 278 files.

Design tokens

A feature page token registry (feature-page-token-registry.ts) tracks all design tokens used across feature pages, with auto-generated statistics to prevent token sprawl. Tokens cover colour, spacing, typography, and dark mode overrides.

Responsive & accessible

• Mobile-first responsive design using Tailwind’s responsive utilities plus page-specific media queries
• Dark mode support via CSS class strategy
• Keyboard-friendly interactions across shared primitives and major workflows
• ARIA attributes are used across shared interactive components
• Reduced motion support via prefers-reduced-motion

Testing & Quality

Test runner

Vitest (not Jest) is the main test runner. Tests live in tests/ mirroring the src/ structure, with Playwright covering critical-path browser journeys under tests/e2e.

Test strategy

Testing patterns

• Pure function extraction: complex logic (signal detection, scoring) is extracted into pure functions for deterministic testing
• Schema validation tests: Zod schemas are tested against edge cases (empty data, malformed input, boundary values)
• Mock Firestore: test doubles for Firestore operations enable fast, isolated tests
• 281 *.test.ts files, 2,485 tests across unit, integration, API-route, extension, and Playwright critical-path coverage