# Technical Architecture

## 1. Purpose

This document translates the product scope in [PRD.md](C:\Users\Admin\Documents\OpenAI_Codex\Skola_Word_Plugin\PRD.md) into the implementation architecture for the current Skola prototype and the next build phases.

Skola is being built as a Microsoft Word add-in that combines:

- academic reference management,
- editing and proofing,
- grounded AI authoring assistance,
- evidence search for highlighted claims.

## 2. Current Implementation Snapshot

As of 2026-04-09, the local prototype includes:

- an Office.js Word add-in using the add-in-only XML manifest format,
- `VersionOverridesV1_0` command definitions for a `Skola` custom tab and task pane entry points,
- a pane-first navigation system that works even when custom ribbon visibility is inconsistent,
- a webpack-served add-in frontend on `https://127.0.0.1:3000`,
- a Fastify API scaffold on `http://127.0.0.1:4000`,
- shared TypeScript contracts in `packages/shared`.

The most important architecture decision so far is compatibility-first hosting for the Word pane:

- the original module-based dev host was replaced,
- the current add-in uses a classic webpack bundle,
- the frontend is transpiled for older Office webviews,
- polyfills are loaded before the app UI starts.

## 3. Architecture Drivers

- **Word-native workflow:** the product must feel like an academic workspace inside Word, not a detached web tool.
- **Compatibility:** the add-in must tolerate older Office webviews and inconsistent ribbon support.
- **Formatting safety:** document edits must be previewable, intentional, and reversible.
- **Evidence grounding:** academic AI output must distinguish validated evidence from model synthesis.
- **Institution readiness:** privacy, provider controls, and deployment governance must remain first-class concerns.
- **Modularity:** UI, API, reference services, retrieval, and orchestration should evolve independently.

## 4. Repository Architecture

```text
.
|-- apps
|   |-- api
|   `-- word-addin
|-- docs
|   `-- TECHNICAL_ARCHITECTURE.md
|-- packages
|   `-- shared
|-- PRD.md
|-- README.md
`-- actionplan.md
```

### Package Responsibilities

- `apps/word-addin`
  - add-in manifest,
  - task pane shell,
  - command surface pages,
  - pane-first workflow rendering,
  - Office document interaction.
- `apps/api`
  - health endpoint,
  - proofread endpoint,
  - AI action endpoint,
  - support-claim endpoint,
  - future service integration boundary.
- `packages/shared`
  - request and response contracts,
  - enums for citation styles, proofread modes, AI actions, and support-search intents.

## 5. Runtime Architecture

```mermaid
flowchart LR
  A["Microsoft Word Desktop"] --> B["Skola XML Manifest"]
  B --> C["Task Pane Host (taskpane.html)"]
  B --> D["Command Surface (commands.html)"]
  C --> E["Webpack Bundle + Polyfills"]
  E --> F["Pane-first Skola UI"]
  F --> G["Office.js / Word APIs"]
  F --> H["Skola API (Fastify)"]
  H --> I["AI Orchestration Layer (future)"]
  H --> J["Reference Connectors (future)"]
  H --> K["Retrieval / Indexing Layer (future)"]
```

## 6. Word Add-in Client Architecture

### 6.1 Manifest Strategy

The add-in uses the add-in-only XML manifest model for broad Office compatibility.

Key decisions:

- `manifest.xml` remains the primary deployment artifact,
- `VersionOverridesV1_0` defines command surface controls,
- `PrimaryCommandSurface` defines the custom `Skola` tab and buttons,
- `ShowTaskpane` actions route users into different task pane views,
- the pane itself remains the canonical navigation surface because some Word clients do not reliably expose custom ribbon UI.

### 6.2 Frontend Entry Points

The frontend currently uses three HTML entry files:

- `taskpane.html`
  - Word task pane host
- `commands.html`
  - command runtime host
- `index.html`
  - compatibility mirror of the task pane host

The runtime entry code is:

- `src/taskpane.ts`
  - loads polyfills and the main pane app
- `src/commands.ts`
  - loads polyfills and command initialization
- `src/main.ts`
  - renders the pane UI and handles workflow interaction

### 6.3 Build And Host Strategy

The current add-in frontend is served with webpack rather than Vite.

Reason:

- the older Word webview on the current Windows client failed to execute module-based dev entry scripts,
- the task pane shell loaded but remained visually blank,
- switching to a classic injected script bundle resolved that compatibility path.

Current host characteristics:

- webpack dev server over HTTPS,
- Office dev certificates via `office-addin-dev-certs`,
- ES5-compatible web target,
- startup polyfills for fetch, async/runtime support, and DOM helpers,
- no dependency on `type="module"` page entry.

### 6.4 UI Architecture

The pane UI is state-driven and centered on five top-level workspaces:

- `Dashboard`
- `Referencing`
- `Review`
- `Edit`
- `Support Claim`

The `Referencing` workspace includes nested menu panels for:

- `Import Citation`
- `Delete Selected`
- `All Sources`
- `New Group`
- `Style`
- `Figures`
- `Tables`
- `Abbreviations`

The pane is intentionally the primary UX surface so the product still works when ribbon behavior varies by Office version.

## 7. Word Integration Boundaries

### Current Word Operations

- detect whether Office is ready,
- read the current selection text,
- insert approved draft text back at the selection,
- keep selection-aware workflows inside the pane.

### Not Yet Implemented

- citation anchors bound to document ranges,
- bibliography regeneration in the Word document,
- figure/table caption automation,
- list of figures/tables refresh,
- abbreviation extraction from the document,
- cross-reference insertion and maintenance,
- track-changes-aware insertion or diff rendering.

## 8. API Layer

### Current Shape

The API is a lightweight Fastify service with scaffold routes for:

- `GET /health`
- `POST /v1/proofread`
- `POST /v1/ai/actions`
- `POST /v1/references/support-claim`

These routes currently return placeholder data so the Word add-in can be developed against stable contracts before real service integrations are added.

### API Responsibilities

- receive structured requests from the add-in,
- normalize frontend inputs,
- return UI-friendly response contracts,
- later enforce auth, policy, provider configuration, telemetry, and persistence.

## 9. Shared Contract Layer

`packages/shared` currently defines the early domain boundary for:

- citation styles,
- proofread modes,
- AI actions,
- support-claim intents,
- proofread request and response shapes,
- AI action request and response shapes,
- support-claim request and result shapes,
- health response shape.

This package is the source of truth for the client/API contract and should continue to stay narrow and explicit.

## 10. Future Service Layers

### 10.1 AI Orchestration

Planned responsibilities:

- intent classification,
- prompt construction,
- retrieval-aware context assembly,
- grounded vs ungrounded response labeling,
- warning generation,
- citation fabrication prevention.

### 10.2 Reference Service

Planned responsibilities:

- citation metadata normalization,
- source deduplication,
- style rendering,
- bibliography generation,
- in-document citation insertion,
- figure/table/abbreviation document helpers.

### 10.3 Retrieval Layer

Planned responsibilities:

- document chunking and indexing,
- uploaded-material ingestion,
- institution knowledge retrieval,
- evidence ranking for AI actions,
- evidence ranking for support-claim search.

### 10.4 Academic Search Connectors

Likely providers:

- Crossref,
- OpenAlex,
- Semantic Scholar,
- PubMed,
- licensed Scopus access,
- Google Scholar only through compliant deep-link or approved integration paths.

## 11. Data And Storage Direction

### Prototype State

The current implementation is largely local and in-memory:

- source groups and source records are stored in frontend state,
- API responses are scaffolded,
- no persistent user library exists yet,
- no retrieval store exists yet.

### Production Direction

- relational database for users, institutions, references, citation instances, preferences, and audit data,
- object storage for uploaded files and document artifacts,
- vector-capable retrieval store for document and source chunks,
- secret-managed provider credentials for AI and external connectors.

## 12. Request Flows

### 12.1 Proofread Flow

1. User highlights text in Word.
2. Pane reads the current selection through Office.js.
3. Pane sends `POST /v1/proofread`.
4. API returns proofing suggestions.
5. Pane shows the output in the activity panel.
6. Later phases will support accept/reject insertion patterns.

### 12.2 Rewrite Or Add Section Flow

1. User highlights text.
2. User opens `Edit` and chooses `Rewrite` or `Add Section`.
3. Pane sends `POST /v1/ai/actions`.
4. API returns a draft plus source cards and warnings.
5. User reviews the draft in the activity panel.
6. User inserts the latest draft back into Word.

### 12.3 Support Claim Flow

1. User highlights a sentence or claim.
2. User opens `Support Claim`.
3. Pane sends `POST /v1/references/support-claim`.
4. API returns normalized academic source candidates.
5. Pane shows rationale, venue, DOI, and evidence warnings.
6. Later phases will support direct citation insertion from those results.

### 12.4 Referencing Flow

1. User opens `Referencing`.
2. User imports `.ris`, `.xml`, or `.enw` files, searches the local source list, or creates a source group.
3. Pane maintains a local source library state.
4. Later phases will parse full reference metadata and bind sources to live Word citation objects.

## 13. Compatibility Notes

The add-in currently needs to support a Word client that:

- can sideload Office add-ins,
- can show task panes,
- may not expose custom ribbon tabs consistently,
- may use an older webview with weaker ES module support.

Therefore the architecture now explicitly assumes:

- pane-first navigation must remain a first-class UX,
- the task pane host must not require module-only browser features,
- startup failures should render visible error UI instead of silent blank panes,
- Word restart and manifest reload are part of the practical dev workflow.

## 14. Local Development View

### Services

- Word add-in host: `https://127.0.0.1:3000`
- API: `http://127.0.0.1:4000`

### Commands

```powershell
npm install
npm run dev:api
npm run dev:word
npm run sideload:word
```

### Verification

```powershell
npm run typecheck
npm run build
npm run validate:manifest
```

## 15. Implementation Status

### Completed In The Current Baseline

- monorepo scaffold,
- shared contracts,
- local API scaffold,
- add-in XML manifest,
- pane-first workflow UI,
- referencing submenu structure,
- local source library interactions,
- compatibility migration from module-based hosting to webpack bundling,
- Word sideload and local runtime verification.

### Next Major Engineering Milestones

1. Parse real citation metadata from imported files.
2. Persist user libraries and document session state.
3. Connect real AI and academic search providers.
4. Bind figure, table, abbreviation, and bibliography workflows to actual Word document structures.
5. Revisit shared runtime or richer ribbon coordination on a newer supported Word client.