Spada Libreria Assistant

Expert assistant for developing and maintaining the Spada Libreria platform, a Next.js application for studying Bolognese fencing treatises with interactive glossaries, annotations, and multi-language support.

Project Context

Spada Libreria is a **local-only learning platform** for studying historical Italian fencing treatises. The application displays texts in Italian, French, and English with interactive glossary tooltips, a comprehensive annotation system, and cross-treatise search capabilities. This is a beginner-friendly project for developers transitioning from C/systems programming to web technologies.

Tech Stack

Core Architecture Principles

1. Content/Code Separation

2. Glossary Term Linking

3. Multi-Language Support

4. Annotation Class Architecture

**Object-oriented design with factory pattern:**

5. Search System Architecture

**Three-layer search architecture:**

6. LocalStorage Utility (CRITICAL)

**MANDATORY centralized storage access:**

Project Structure

```

src/

├── app/ # Next.js App Router

│ ├── api/

│ │ ├── annotations/ # Annotation persistence

│ │ └── content/ # Content loading

├── components/ # React components

│ ├── BolognesePlatform.tsx # Main platform

│ ├── TextParser.tsx # Glossary link parser

│ ├── Term.tsx # Tooltip component

│ ├── SearchBar.tsx # Search UI

│ ├── AnnotationPanel.tsx # Annotation editor

│ ├── AnnotationBadge.tsx # Tag display

│ └── ColorPicker.tsx # Annotation colors

├── contexts/ # State management

│ ├── AnnotationContext.tsx

│ ├── AnnotationDisplayContext.tsx

│ └── SearchContext.tsx

└── lib/ # Utilities

├── dataLoader.ts

├── searchEngine.ts

├── highlighter.ts

├── localStorage.ts # REQUIRED for all storage

└── annotation/ # OOP architecture

├── Annotation.ts # Base class

├── AnnotationRegistry.ts # Factory

├── Weapons.ts

├── Guards.ts

└── [7 more classes]

data/

├── glossary.yaml

└── treatises/ # YAML treatise files

scripts/

├── extract_book.py # PDF extraction

└── yaml_annotate.py # Annotation script

```

Development Commands

Node.js / Next.js

```bash

npm install # Install dependencies

npm run dev # Start dev server (http://localhost:3000)

npm run build # Production build

npm run lint # ESLint

npm test # Jest + React Testing Library

npm test -- --watch # Watch mode

```

Python Scripts

```bash

uv sync # Sync Python dependencies

uv add <package> # Add Python dependency (NEVER edit pyproject.toml manually)

uv run scripts/extract_book.py --pdf marozzo --pages "34-102"

uv run scripts/yaml_annotate.py

```

Code Style Guidelines

TypeScript / React

Python

Data File Formats

Glossary Entry (`data/glossary.yaml`)

```yaml

term_key:

term: Display Term

type: Category

definition:

fr: French definition

en: English definition

translation:

fr: French translation

en: English translation

```

Treatise Section (`data/treatises/*.yaml`)

```yaml

title: Section Title

metadata:

master: master_name

work: Work Name

book: 1

chapter: 1

year: 1536

content:

it: Italian text with {glossary_terms}

fr: French text with {glossary_terms}

en_versions:

- translator: "Name"

text: English text with {glossary_terms}

annotation:

id: anno_1234567890_unique

weapons: [Spada sola]

weapon_type: "Épée aiguisée"

guards_mentioned: [Coda Longa e Stretta]

techniques: [Stringere]

measures: [Largo, Mezzo]

strategy: [provocation]

strikes: [Mandritto, Fendente]

targets: [Tête, Bras]

guards_count: {"Coda Longa e Stretta": 2}

techniques_count: {"Stringere": 1}

strikes_count: {"Mandritto": 3}

targets_count: {"Tête": 2}

```

**IMPORTANT**: Annotation fields live in the `annotation` section, NOT `metadata`. The `metadata` section contains only bibliographic information.

Critical Rules

Python Dependency Management

**NEVER manually edit `pyproject.toml` dependencies**

**ALWAYS use**: `uv add <package-name>`

Example:

```bash

✅ Correct

uv add pyyaml

❌ Wrong: Manually editing pyproject.toml

```

LocalStorage Access

**NEVER use `localStorage` directly**

**ALWAYS use**: `LocalStorage` utility from `@/lib/localStorage`

Example:

```typescript

// ✅ Correct

import { LocalStorage } from '@/lib/localStorage';

const data = LocalStorage.getItem<MyType>('key') ?? defaultValue;

LocalStorage.setItem('key', data);

// ❌ Wrong

const data = localStorage.getItem('key');

localStorage.setItem('key', JSON.stringify(data));

```

Server/Client Component Separation

Testing Guidelines

JavaScript/TypeScript (Jest + React Testing Library)

Python (pytest)

When Working on This Project

1. **Content Changes**: Edit YAML files in `data/`, never hardcode in TypeScript

2. **New Annotation Types**: Extend `Annotation` base class, register in `AnnotationRegistry`

3. **Storage Operations**: Always use `LocalStorage` utility, never direct `localStorage`

4. **Search Features**: Modify `SearchEngine`, update `SearchContext`, adjust `Highlighter`

5. **Python Scripts**: Use `argparse`, follow PEP 8, add dependencies via `uv add`

6. **Styling**: Use Tailwind utility classes exclusively

7. **API Routes**: Follow Next.js App Router conventions in `src/app/api/`

Important Context

Example Workflows

Adding a New Annotation Type

1. Create new class in `src/lib/annotation/NewType.ts` extending `Annotation`

2. Implement `getChipStyle()`, `getTextStyle()`, validation logic

3. Register in `AnnotationRegistry.ts`

4. Update `AnnotationPanel.tsx` UI

5. Add field to treatise YAML `annotation` section

Implementing New Search Feature

1. Update search logic in `src/lib/searchEngine.ts`

2. Modify `SearchContext.tsx` to manage new state

3. Adjust `Highlighter.ts` for visual feedback

4. Update `SearchBar.tsx` UI controls

5. Test across multiple treatise sections

Extracting New Treatise from PDF

1. Run: `uv run scripts/extract_book.py --pdf <author> --pages "X-Y"`

2. Review generated YAML in `data/treatises/`

3. Add `{glossary_terms}` markup manually

4. Run: `uv run scripts/yaml_annotate.py` to add annotations

5. Verify in dev server

Key Files Reference