# Specification: Translation Dictionary for Living Christianity

## Overview

"Sanasto Wiki" is a web-based glossary for simultaneous translators in the living Christianity. The application provides publicly accessible translations while restricting editing and commenting to invited contributors.

---

## Core Concepts

### Supported Languages

Initial seed data:

| Code | Name | Native Name | Sort Order |
|------|------|-------------|------------|
| fi | Finnish | Suomi | 1 |
| en | English | English | 2 |
| sv | Swedish | Svenska | 3 |
| no | Norwegian | Norsk | 4 |
| de | German | Deutsch | 5 |
| ru | Russian | Русский | 6 |


Language codes are fixed because translations are stored in columns on `entries`. The `supported_languages` table controls labels, ordering, and whether a language is active. To add a language, you must add a new column to `entries` and add a corresponding row to `supported_languages`.

### Entry
An entry represents a translatable unit which may be:

- `word` — Single word
- `phrase` — Multi-word expression or idiom, sentence
- `proper_name` — Person's name (for consistent transliteration)
- `title` — Book, publication, or hymn title
- `reference` — Biblical or doctrinal term
- `other` — Any other translatable text unit

Each entry has translations in multiple languages.

### Suggested Meaning
When translators disagree on a translation or want to suggest alternatives (regional variations, contextual meanings, etc.), they can submit a suggested meaning for community review.

---

## Technical Stack

* Framework: Rails 8
* Database: SQLite with FTS5
* Authentication: Rails 8 built-in authentication
* Authorization: Invitation-only for contributors
* Deployment: Kamal

---

## Setup / First User

When setup has not been completed, the `/setup` route is accessible for creating the initial admin account. Completion is tracked in the database. The first user created will be the system's default contact email (accessible via `User.first.email`).

For detailed setup instructions, see [SETUP_GUIDE.md](docs/SETUP_GUIDE.md).

**Quick Start:**
1. Deploy the application
2. Navigate to `/setup`
3. Create your admin account
4. Start inviting contributors

---

## Authentication Flow

### Public Access
- No authentication required for browsing and searching entries
- Read-only access to all dictionary content

### Invitation-Only Registration
- Admins send email invitations with unique tokens
- Invited users register by setting name and password
- `invitation_token` cleared after successful registration

### Login & Sessions
- Email + password authentication
- Session-based (encrypted cookies, Rails default)
- Optional "remember me" for extended sessions

### Authorization
- **Contributor**: Create/edit entries, add comments, suggest translations
- **Reviewer**: All contributor actions + review suggestions, verify entries
- **Admin**: All actions + invite users, manage roles

### Security
- Passwords hashed with bcrypt
- Rate limiting on login attempts
- Invitation tokens expire after 14 days

---

## Database Schema

see `db/structure.sql`

---

## Initial Data

See 'public/Kristillisyyden sanasto ver 23.5.2013.xlsx'

---

## User Roles & Permissions

| Action | Public | Contributor | Reviewer | Admin |
|--------|--------|-------------|----------|-------|
| View entries | ✓ | ✓ | ✓ | ✓ |
| Search entries | ✓ | ✓ | ✓ | ✓ |
| Create entry | | ✓ | ✓ | ✓ |
| Edit entry | | ✓ | ✓ | ✓ |
| Add comment | | ✓ | ✓ | ✓ |
| Submit suggested meaning | | ✓ | ✓ | ✓ |
| Review suggested meanings | | | ✓ | ✓ |
| Mark entry as verified | | | ✓ | ✓ |
| Invite new users | | | | ✓ |
| Manage users | | | | ✓ |

---

## Features

### Public Features

**Search & Browse**
- Full-text search across all languages
- Filter by category
- Alphabetical browsing per language
- View entry with all translations
- Download the entries table as an XLSX file, without :id attribute

### Contributor Features

**Entry Management**
- Create new entries with translations in known languages
- Edit existing translations
- Leave empty translations for others to fill in
- Add notes/context to entries
- View edit history

**Discussion**
- Add comments to entries
- Submit alternative translations as suggested meanings
- Participate in translation discussions

### Reviewer Features

**Quality Control**
- Review and approve/reject suggested meanings
- Mark entries as verified
- Merge duplicate entries

### Admin Features

**User Management**
- Send invitations via email
- Assign/change user roles
- Deactivate users

**System Management**
- Bulk import/export (CSV)
- Database backup

---

## User Interface

### Pages

1. **Home/Search** — Search box, quick stats, recent entries
2. **Browse** — Alphabetical listing with language selection
3. **Entry View** — Single entry with all translations, comments, suggested meanings
4. **Entry Edit** — Form for editing translations (contributors only)
5. **New Entry** — Form for creating entries (contributors only)
6. **Suggested Meanings Queue** — List for reviewers
7. **User Profile** — Personal settings, contribution history
8. **Admin Dashboard** — User management, invitations, stats

### Design Principles
- Clean, readable typography (translations must be easy to read quickly)
- Mobile-friendly (translators may use during services)
- Fast search (primary use case)
- Clear visual distinction between verified and unverified entries

---

## API (Public Sync)

Public JSON endpoint for syncing entries:
```
GET /api/entries
GET /api/entries?since=2026-01-01T12:00:00Z
```

Responses include all language columns, category and `updated_at`. The optional `since`
parameter filters by `updated_at` (ISO8601).

Swagger docs:
```
GET /api/swagger
```

Swagger UI:
```
GET /api
```

## Deployment

Server: Single VPS with Kamal
Database: SQLite with Litestream for replication/backup
Assets: Propshaft (Rails 8 default)
Background Jobs: Solid Queue (for invitation emails)


## Future Considerations

Export to PDF/print format for offline use
Audio pronunciation recordings
Mobile app
Offline mode with sync
Additional languages via migration