# Future Jobs Firebase + Cloudflare Spec

## Purpose

This document defines the first production-ready backend shape for the standalone Future Jobs app.

The app has two surfaces:

- public explorer for browsing approved future-job intelligence
- admin brain builder for document ingest, review, and publishing

Cloudflare should handle delivery, edge APIs, and background orchestration.
Firebase should handle auth, database, and file storage.

## Platform Split

### Cloudflare responsibilities

- serve the frontend app on Cloudflare Pages
- expose Worker API routes for admin and public reads
- run ingest and publish orchestration
- queue long-running ingest jobs
- optionally cache approved explorer responses

### Firebase responsibilities

- Firebase Auth for admin access
- Firestore for role, source, and workflow data
- Firebase Storage for uploaded source files

## Data Model

Use a draft -> approved -> derived flow.

### `roles`

Approved role records used by the public explorer and downstream products.

Suggested document fields:

- `id`
- `legacyId`
- `roleName`
- `roleFamily`
- `roleType`
- `transitionCategory`
- `industries`
- `functionLabels`
- `roleRelevance`
- `status`
- `audience`
- `summary`
- `description`
- `matchInputs`
- `backboneRefs`
- `taskClusters`
- `pressureProfile`
- `frictionFactors`
- `marketSignals`
- `lcapProfile`
- `humanAdvantage`
- `risingSkills`
- `fbCapabilityProfile`
- `developmentActions`
- `adjacentRoles`
- `studyPaths`
- `institutionReadinessRelevance`
- `starterNextMove`
- `notes`
- `sourceSummary`
- `publishedAt`
- `updatedAt`

Use `industries` and `functionLabels` as separate axes:

- `industries` = sector context such as Healthcare, Retail, Finance
- `functionLabels` = work function such as Marketing, Finance, Operations, Data, Care, Education

### `roleKnowledge`

Approved source-linked knowledge attached to existing roles.

Suggested document fields:

- `id`
- `roleId`
- `roleName`
- `sourceDocumentId`
- `sourceLabel`
- `snippetCount`
- `snippets`
- `insightTags`
- `confidenceScore`
- `approved`
- `approvedAt`
- `updatedAt`

### `sourceDocuments`

Uploaded reports, pasted text captures, or structured lists.

Suggested document fields:

- `id`
- `sourceLabel`
- `sourceType`
- `industryLabels`
- `fileName`
- `storagePath`
- `mimeType`
- `rawText`
- `textLength`
- `uploadStatus`
- `uploadedBy`
- `createdAt`
- `updatedAt`

### `ingestRuns`

One record per analysis job.

Suggested document fields:

- `id`
- `sourceDocumentId`
- `sourceLabel`
- `sourceType`
- `industryLabels`
- `parserVersion`
- `status`
- `duplicateCount`
- `insightCount`
- `proposedRoleCount`
- `errorMessage`
- `startedAt`
- `completedAt`
- `createdAt`

### `proposedRoles`

Draft role candidates waiting for review.

Suggested document fields:

- `id`
- `proposedRoleId`
- `normalizedRole`
- `sourceDocumentId`
- `sourceLabel`
- `reviewStatus`
- `reviewNotes`
- `matchedExistingRoleId`
- `createdAt`
- `updatedAt`

### `duplicateCandidates`

Potential matches between new inputs and existing roles.

Suggested document fields:

- `id`
- `sourceDocumentId`
- `incomingRoleName`
- `matchedRoleId`
- `matchedRoleName`
- `matchMethod`
- `matchScore`
- `reviewStatus`
- `createdAt`
- `updatedAt`

### `publishBatches`

Tracks admin publish actions from draft content into approved explorer data.

Suggested document fields:

- `id`
- `publishedBy`
- `roleCount`
- `knowledgeCount`
- `notes`
- `createdAt`

## Storage Layout

Use Firebase Storage paths like:

- `future-jobs/sources/{sourceDocumentId}/original/{filename}`
- `future-jobs/sources/{sourceDocumentId}/derived/raw-text.txt`
- `future-jobs/exports/{publishBatchId}/brain-export.json`

## API Shape

Cloudflare Workers can expose:

- `GET /api/explorer/roles`
- `GET /api/explorer/roles/:id`
- `GET /api/explorer/stats`
- `POST /api/admin/sources`
- `POST /api/admin/ingest/:sourceDocumentId`
- `GET /api/admin/ingest-runs/:id`
- `GET /api/admin/review/proposed-roles`
- `POST /api/admin/review/proposed-roles/:id/approve`
- `POST /api/admin/review/proposed-roles/:id/reject`
- `POST /api/admin/review/knowledge/:id/approve`
- `POST /api/admin/publish`

## Workflow

### Admin ingest flow

1. admin uploads a file or pastes text
2. create a `sourceDocuments` record
3. upload file to Firebase Storage when relevant
4. enqueue ingest job in Cloudflare
5. parser extracts structured rows and article insights
6. save duplicates, proposed roles, and knowledge drafts
7. admin reviews results
8. approved items are published to `roles` and `roleKnowledge`

### Public explorer flow

1. user opens the explorer
2. frontend requests approved role data only
3. Cloudflare Worker reads from Firestore and can cache the response
4. explorer never reads draft or admin-only content

## Integration Boundary

The Future Jobs app is the source of truth for role intelligence.

Other products such as Crack My Future should read:

- approved roles
- approved role knowledge
- approved study paths
- approved future-readiness signals

They should not read raw ingest results directly.

## Frontend Views

### Public views

- home
- explorer list
- role detail modal or page

### Admin views

- source ingest
- duplicate review
- knowledge review
- proposed role review
- publish summary

## Immediate Build Priority

1. keep the current branded explorer
2. keep the current branded brain builder as the admin shell
3. replace local browser persistence with Firebase-backed records
4. add review and publish controls before public consumption