From 5e15ed71d4cfc2c93ffd637716ae756b78c0cdea Mon Sep 17 00:00:00 2001 From: cubap Date: Tue, 14 Jul 2026 13:23:02 -0500 Subject: [PATCH 1/2] Add contributing guide and project documentation (#8) --- CONTRIBUTING.md | 73 ++++++++++++++++++++++++++++ docs/export-tpen.md | 75 +++++++++++++++++++++++++++++ docs/tpen-tools.md | 69 +++++++++++++++++++++++++++ docs/tpen3.md | 113 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 330 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 docs/export-tpen.md create mode 100644 docs/tpen-tools.md create mode 100644 docs/tpen3.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4b7c794 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contribute to Research Computing at Saint Louis University + +Welcome! This repository contains research software development at the Center for Digital Humanities, Saint Louis University. Below is how to get started. + +## What to work on + +Not sure where to start? The best signal is the issue tracker. + +- **`good first issue`** — meant for you. Clear scope, minimal setup, mentor available. +- **`help wanted`** — open to anyone. May have trade-off decisions; feel free to ask. +- **`bug`** — confirmed problems. Fix or reproduce → discuss → PR. +- **`enhancement`** — feature requests. Propose a solution → get alignment → build it. + +No label? That's internal work-in-progress — open an issue first to coordinate. + +## Communication and etiquette + +- **Issues are for scoping, PRs are for code.** Discuss the problem in an issue. Implement the solution in a PR with a clear description. +- **Reference upstream issues.** If your change addresses an issue, mention it (`Fixes #12`, `Closes #45`) so the link is automatic. +- **Ask early, merge fast.** A short message ("I'm tackling this — aim for Friday") is worth more than a silent week of work. +- **No rush.** This is research software, not a startup. Clear work beats fast work. + +## Getting started with a project + +Each project has its own setup. Pick one below: + +| Project | Focus | Status | +|---------|-------|--------| +| [TPEN3](/docs/tpen3.md) | New annotation platform | In development | +| [tpen.tools](/docs/tpen-tools.md) | Utilities and services | Mature | +| [Export TPEN](/docs/export-tpen.md) | Export small projects as static files | Mature | + +**Note:** the legacy T-PEN 2.8 platform is not yet documented here — coming soon. + +## Development conventions + +### Branching + +- Work on a named branch, not `main`. +- Descriptive names help: `fix/login-broken`, `feat/new-tool`, `docs/readme-update`. +- Open early — a draft PR is a great way to get feedback before it's finished. + +### Commits + +- Write messages that explain *why*, not just *what*. +- Reference the issue when relevant: `Fix #23 — handle edge case in parser`. +- Small, reviewable commits beat monoliths. + +### Pull requests + +- Target `main` unless told otherwise. +- Describe what changed and why in the PR body. +- Include screenshots for UI changes. +- Request at least one reviewer. + +## Testing your changes + +- **Run it locally** before opening a PR — at minimum, start the app and hit the changed code path. +- **Check the real URLs.** If the app is deployed, verify your branch build or a preview deploys correctly. +- **Common breakage spots:** authentication flows, API endpoints, and anything that touches the TPEN 2.8 archive. + +## Ready to contribute? + +1. **Pick an issue** — `good first issue` is the friendliest start. +2. **Fork and branch** — fork the repo, create a branch for your work. +3. **Set up the project** — follow the guide linked above for your target project. +4. **Open a PR** — describe your change, reference the issue, request a reviewer. + +Stuck? Open an issue or ask in an existing one — we're here to help. + +## License + +By contributing, you agree your contributions are licensed under the project's license (see each project page for details). diff --git a/docs/export-tpen.md b/docs/export-tpen.md new file mode 100644 index 0000000..c61c1aa --- /dev/null +++ b/docs/export-tpen.md @@ -0,0 +1,75 @@ +# Export TPEN — Static Project Export Tool + +**Repository:** [CenterForDigitalHumanities/ExportTPEN](https://github.com/CenterForDigitalHumanities/ExportTPEN) +**Live URL:** [export.t-pen.org](https://export.t-pen.org) +**Status:** Mature and actively used + +## What it is + +A simple web app that takes a TPEN 2.8 project and exports it as a static, standalone directory of files — HTML pages, JSON data, and images. The result can be hosted anywhere without a database. + +## Project structure + +``` +ExportTPEN/ +├── index.html # Main app page (UI + logic) +├── export.html # Export status page +├── js/ # JavaScript modules +├── css/ # Stylesheets +└── images/ # Static assets +``` + +The entire app is a single `index.html` with inline JavaScript and CSS — simple to modify, no build step required. + +## Setup for development + +```bash +# Clone the repository +git clone https://github.com/CenterForDigitalHumanities/ExportTPEN.git +cd ExportTPEN + +# Serve via any static file server +npx http-server . -p 8080 +``` + +Open `http://localhost:8080`. The app calls the TPEN 2.8 API, so you need network access to `t-pen.org`. + +## How it works + +1. User provides a TPEN 2.8 project ID or URL. +2. The app fetches project data from the TPEN 2.8 API (pages, layers, annotations, images). +3. It generates static files: + - `index.html` — viewable project page + - `project.json` — complete project data + - `page-N.json` — per-page annotation data + - `images/` — cached page images +4. The result is downloadable as a ZIP or savable to a filesystem. + +## Common contribution areas + +- **Export format improvements** — better JSON structure, new file types +- **UI polish** — clearer progress indicators, error messages +- **Edge cases** — large projects, missing resources, special characters +- **Documentation** — what the exported files look like and how to use them + +## Testing + +1. Start the local server +2. Open the app in your browser +3. Enter a real TPEN 2.8 project URL or ID +4. Watch the export progress and inspect the output +5. Open the generated `index.html` to verify it renders + +Use small projects for quick iteration. The live site at `export.t-pen.org` is always available for comparison. + +## Branching and PRs + +- Work on a named branch off `main`. +- Open a PR targeting `main`. +- Describe your change and what you tested. +- Request a reviewer from the core team. + +## Contact + +- Repository owner: Center for Digital Humanities, Saint Louis University +- See the [Contributing Guide](/CONTRIBUTING.md) for general contribution conventions. diff --git a/docs/tpen-tools.md b/docs/tpen-tools.md new file mode 100644 index 0000000..719a4cf --- /dev/null +++ b/docs/tpen-tools.md @@ -0,0 +1,69 @@ +# tpen.tools — Utilities and Services + +**Repository:** [CenterForDigitalHumanities/tpen.tools](https://github.com/CenterForDigitalHumanities/tpen.tools) +**Live URL:** [tpen.tools](https://tpen.tools) +**Status:** Mature and actively used + +## What it is + +A collection of web-based tools for interacting with TPEN data — project management, annotation editing, image processing, and interoperability utilities. Each tool is a standalone page that can be embedded or opened directly. + +## Project structure + +``` +tpen.tools/ +├── index.html # Landing page / tool directory +├── tools/ # Individual tool pages +│ ├── project/ # Project management tools +│ ├── annotation/ # Annotation editing tools +│ ├── image/ # Image processing utilities +│ └── export/ # Data export helpers +├── js/ # Shared JavaScript modules +├── css/ # Stylesheets +└── images/ # Static assets +``` + +## Setup for development + +This is a static site — no build step or backend required. + +```bash +# Clone the repository +git clone https://github.com/CenterForDigitalHumanities/tpen.tools.git +cd tpen.tools + +# Serve via any static file server +npx http-server . -p 8080 +``` + +Open `http://localhost:8080` in your browser. Most tools call the TPEN 2.8 API directly, so they work as-is — though some endpoints may require authentication. + +## Common contribution areas + +- **New tools** — add a page under `tools/` that solves a specific task +- **Shared modules** — factor out common patterns into `js/` for reuse +- **Tool improvements** — better UX, edge-case handling, accessibility +- **Documentation** — each tool should describe its inputs, outputs, and limitations + +## Testing + +Tools are tested by opening them and exercising the core workflow: + +1. Start the local server (`npx http-server`) +2. Open the tool page +3. Perform the primary action (load a project, save an annotation, export data) +4. Check the browser console for errors + +Some tools depend on the TPEN 2.8 API — make sure you can reach `t-pen.org` from your environment. + +## Branching and PRs + +- Work on a named branch off `main`. +- Open a PR targeting `main`. +- Describe your change and link the tool URL. +- Request a reviewer from the core team. + +## Contact + +- Repository owner: Center for Digital Humanities, Saint Louis University +- See the [Contributing Guide](/CONTRIBUTING.md) for general contribution conventions. diff --git a/docs/tpen3.md b/docs/tpen3.md new file mode 100644 index 0000000..ee6911e --- /dev/null +++ b/docs/tpen3.md @@ -0,0 +1,113 @@ +# TPEN3 — New Annotation Platform + +**Repository:** [CenterForDigitalHumanities/TPEN](https://github.com/CenterForDigitalHumanities/TPEN) +**Live URL:** [three.t-pen.org](https://three.t-pen.org) (in development) +**Status:** In development + +## What it is + +TPEN3 is the next-generation platform for transcription, annotation, and image-based markup. It succeeds TPEN 2.8 and brings modern tooling — a responsive SPA frontend, a Node.js API backend, and new capabilities for scholarly annotation. + +## Project structure + +``` +TPEN/ +├── api/ # Node.js API backend (routes, controllers, database) +├── web/ # SPA frontend (HTML, CSS, JavaScript) +├── scripts/ # Build and deployment helpers +└── tests/ # Test suites +``` + +Key interaction patterns: + +- **Frontend → API.** All data operations (load project, save annotation, create layer) go through the API, not direct database calls. +- **Canvas-first UI.** The image canvas is the primary workspace; tools orbit around it. +- **Layered annotations.** Annotations are grouped into layers (transcription, commentary, metadata) that can be toggled independently. + +## Setup for development + +```bash +# Clone the repository +git clone https://github.com/CenterForDigitalHumanities/TPEN.git +cd TPEN + +# Install API dependencies +cd api +npm install +cd .. + +# Start the API server +# (requires MongoDB — see .env.example for configuration) +npm start + +# Open the frontend +# Serve web/ via any static file server +npx http-server web/ -p 3000 +``` + +### Required services + +- **MongoDB** — data store for projects, annotations, and users. Can run locally or via a connection string. +- **TPEN 2.8 archive** — read-only access to legacy projects (for import and migration). This is provided by the team. + +### Configuration + +Copy `api/.env.example` to `api/.env` and fill in: + +- Database connection string +- TPEN 2.8 archive endpoint +- Authentication secrets + +## Common contribution areas + +### Frontend (`web/`) + +- Canvas tools and interaction +- UI components (panels, modals, toolbars) +- Responsive layout and accessibility +- New annotation types and layer controls + +### API (`api/`) + +- New endpoints for tools and features +- Database query optimization +- Authentication and permission flows +- Project import/migration tools + +### Cross-cutting + +- **Testing** — unit tests for API routes, integration tests for frontend interactions +- **Documentation** — inline code docs, user-facing guides +- **Performance** — large canvas rendering, annotation list pagination + +## Useful files to know + +| File | Purpose | +|------|---------| +| `api/routes/` | API endpoint definitions | +| `web/js/` | Core JavaScript modules | +| `web/index.html` | Entry point for the SPA | +| `web/css/` | Stylesheets | + +## Testing + +```bash +# API tests +cd api +npm test + +# Frontend (open in browser and check console) +# No formal test runner yet — manual testing via http://localhost:3000 +``` + +## Branching and PRs + +- Work on a named branch off `main`. +- Open a PR targeting `main`. +- Describe your change: what changed, why, and how to test it. +- Request a reviewer from the core team. + +## Contact + +- Repository owner: Center for Digital Humanities, Saint Louis University +- See the [Contributing Guide](/CONTRIBUTING.md) for general contribution conventions. From fb957653df318019f2d2a83ae1cac30b2c3a2308 Mon Sep 17 00:00:00 2001 From: cubap Date: Tue, 14 Jul 2026 15:43:42 -0500 Subject: [PATCH 2/2] add TPEN-IDE doc, remove stale llm-ide, update contributing table --- CONTRIBUTING.md | 1 + docs/tpen-ide.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+) create mode 100644 docs/tpen-ide.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b7c794..c22fa72 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,7 @@ Each project has its own setup. Pick one below: | [TPEN3](/docs/tpen3.md) | New annotation platform | In development | | [tpen.tools](/docs/tpen-tools.md) | Utilities and services | Mature | | [Export TPEN](/docs/export-tpen.md) | Export small projects as static files | Mature | +| [TPEN-IDE](/docs/tpen-ide.md) | Transcription and prompt workspace | Prototype | **Note:** the legacy T-PEN 2.8 platform is not yet documented here — coming soon. diff --git a/docs/tpen-ide.md b/docs/tpen-ide.md new file mode 100644 index 0000000..8eb8ffb --- /dev/null +++ b/docs/tpen-ide.md @@ -0,0 +1,124 @@ +# TPEN-IDE — Transcription and Prompt Workspace + +**Repository:** [cubap/llm-ide](https://github.com/cubap/llm-ide) (early prototype) +**Live URL:** N/A (local file only) +**Status:** Prototype — awaiting move into TPEN-3 monorepo + +## What it is + +TPEN-IDE is a browser-native, zero-install integrated workspace for TPEN +transcription and prompt-driven annotation. It merges two workflows that are +often siloed: + +- **Image-based transcription** — load a canvas image, draw lines, type text. +- **Prompt-based generation** — compose LLM prompts, run them against a + provider, paste or auto-import the output as annotations. + +The result is a single environment where a transcription line can be drafted +by hand or generated by a model, with the same review and export downstream. + +## Project structure + +``` +llm-ide/ +├── index.html # SPA entry point — layout, tool panels, canvas +├── style.css # All presentation — card system, responsive layout +└── README.md # User-facing overview +``` + +There are no build steps, no bundler, and no dependencies. Opening `index.html` +in a browser is sufficient. + +Key interaction patterns: + +- **Canvas-first UI.** The image canvas is the primary workspace; tools orbit + around it just like TPEN 2.8 and TPEN 3. +- **Prompt-as-annotation.** A generated transcription line is stored the same + way as a typed one — the source (human vs model) is metadata, not a + structural difference. +- **Zero setup.** No authentication, no API keys, no server required to open + the tool. + +## Setup for development + +```bash +# Clone or download the files +git clone https://github.com/cubap/llm-ide.git +cd llm-ide + +# Open index.html in any browser +open index.html # macOS +start index.html # Windows +xdg-open index.html # Linux +``` + +No runtime, no package manager, no configuration needed. + +### Moving to TPEN-3 monorepo + +The long-term home for this workspace is `packages/tpen-ide` inside the +[TPEN-3 monorepo](https://github.com/CenterForDigitalHumanities/TPEN-3). That +move brings: + +- Shared TPEN components (CanvasViewer, AnnotationLayer, LineParser). +- Shared services (Annotation, Project, Manifest). +- TPEN authentication and project import flows. +- Coordinated releases alongside TPEN 3. + +Until the monorepo is ready to absorb it, the standalone files are the +source of truth. + +## Common contribution areas + +### Layout and Panels (`index.html`) + +- Canvas tool panel — line drawing, navigation, zoom. +- Prompt tool panel — template selection, parameter input, run controls. +- Annotation panel — review, edit, and export generated lines. +- Responsive layout — split-panel behavior on narrow viewports. + +### Styling (`style.css`) + +- Card and panel visual hierarchy. +- Canvas overlay rendering (lines, highlights, guides). +- Dark mode or accessibility improvements. +- Mobile and tablet breakpoints. + +### Cross-cutting + +- **Testing** — open in multiple browsers, check console, verify canvas + interactions. +- **Documentation** — inline HTML comments, updated README. +- **Monorepo migration** — identifying which TPEN-3 packages to pull in + and refactoring shared code out. + +## Useful files to know + +| File | Purpose | +|------|---------| +| `index.html` | SPA entry point — layout, tool panels, canvas viewer | +| `style.css` | All presentation — card system, responsive layout | + +## Testing + +```bash +# No test runner — open index.html and interact manually +# Check: +# - Canvas loads and responds to zoom/pan +# - Tool panels open and close +# - Prompt panel submits and displays output +# - Console has no errors +``` + +## Branching and PRs + +- Work on a named branch off `main`. +- Open a PR targeting `main`. +- Describe your change: what changed, why, and how to test it. +- Request a reviewer from the core team. + +## Contact + +- Repository author: cubap +- Parent project: [TPEN-3](https://github.com/CenterForDigitalHumanities/TPEN-3) +- See the [Contributing Guide](/CONTRIBUTING.md) for general contribution conventions.