From c6fab5fdbbb9b2af2726b9dfea938411a82415c7 Mon Sep 17 00:00:00 2001 From: wilson Date: Wed, 15 Apr 2026 21:01:31 +0100 Subject: [PATCH] docs: [frontend] Add to docs for the frontend package --- frontend/docs/architecture.md | 32 ++++++++++++++++++++++++++++++++ frontend/docs/design.md | 14 +++++++++----- frontend/docs/domain.md | 9 +++++++++ 3 files changed, 50 insertions(+), 5 deletions(-) create mode 100644 frontend/docs/domain.md diff --git a/frontend/docs/architecture.md b/frontend/docs/architecture.md index 50a3fa2..6ac34c5 100644 --- a/frontend/docs/architecture.md +++ b/frontend/docs/architecture.md @@ -1,7 +1,39 @@ # Frontend Architecture +This document describes the software architecture and aptterns for the web application for language learning application. + This is a web application built using Svelte Kit v5, running on the NodeJS adapter. Follow the svelte kit conventions where possible, e.g. in placing routes, authentication, code. Where possible, this application will use Progressive Web App technologies, to increase its offline performance. + +## Other applications systems + +This application runs on the NodeJS adapter for Svelte-Kit, meaning it has both a client and server available, and it makes use of both. + +The main other component in the language learning app system is the Python-written fastapi HTTP API. The best place to understand all components of the system is through [the root docker-compose](../../docker-compose.yml) + +## Authentication + +Authentication with the HTTP server is through the `Authorization` header, which contains a JWT token. + +This token contains server-validated information, e.g. account roles. We must therefore verify the integrety of this token with the `PRIVATE_JWT_SECRET` environment variable. + +Token and role checking is centralised into the `src/hooks.server.ts` file, which allows authentication on _every_ request. + +## Components + +It is bad practice to simply have a `+page.svelte` component contain all aspects of a page. When convenient, code should be split into smaller component files. + +Where components aren't shared outside of a single page, they live as siblings to the `+page.svelte` file. + +Where components are shared, or are likely to be, they live in `src/components` + +## Styling + +Read [design.md](./design.md) for aesthetic information. + +Application-wide styles live in `src/app.css`. This is where e.g. form and typographic information live, as well as a lot of design tokens, usually as custom values (i.e. variables in CSS). + +Component-level styling should use CSS, which should be object/component oriented, rather than utility-class driven. Where possible, design tokens for spacing, colours, etc. should be used for consistenty. diff --git a/frontend/docs/design.md b/frontend/docs/design.md index 408ad0c..09e0bba 100644 --- a/frontend/docs/design.md +++ b/frontend/docs/design.md @@ -1,12 +1,16 @@ # Design System Document: Language Learning App +This document describes the aesthetic look and feel of the language learning app's web interface. + ## 1. Overview & Creative North Star **Creative North Star: The Digital Archivist** This design system rejects the frantic, "attention-economy" aesthetic of modern web apps. Instead, it draws inspiration from high-end printed journals and architectural minimalism. The goal is to create a "Digital Paper" experience that honours the act of reading. -We break the standard "SaaS dashboard" template by using intentional asymmetry and high-contrast typographic scales. +The app always writes in British, never American English. + +We break the standard "SaaS dashboard" template by using intentional asymmetry and high-contrast typographic scales. Consider classic, intention grid templates of print, and also the visual Bauhaus aesthetic. Layouts with multiple sources of information should feel like a well-composed magazine spread: large, sweeping areas of `surface` punctuated by tight, authoritative `label` groupings. We do not fill space; we curate it. @@ -14,7 +18,7 @@ Layouts which are focused on content, e.g. reading or listening, should feel foc --- -## 2. Colors: The Palette of Focus +## 2. Colours: The Palette of Focus Our palette is rooted in organic, desaturated tones that reduce eye strain and promote deep work. @@ -32,11 +36,11 @@ Our palette is rooted in organic, desaturated tones that reduce eye strain and p Typography is the primary visual asset. We use a sophisticated pairing of **Archivo** (Sans-serif) for functional UI and **Newsreader** (Serif) for the reading experience. -- **Display & Headline (Archivo)**: These are your "Wayfinders." Use `display-lg` (3.5rem) with tight letter-spacing for article titles to create an authoritative, architectural feel. +- **Display & Headline (Archivo)**: (`--font-display`) These are your "Wayfinders." Use `display-lg` (3.5rem) with tight letter-spacing for article titles to create an authoritative, architectural feel. -- **Body (Newsreader)**: This is the soul of the system. `body-lg` (1rem) is the standard for long-form reading. It must have a line-height of at least 1.6 to ensure the "Digital Paper" feel. +- **Body (Newsreader)**: (`--font-body`) This is the soul of the system. `body-lg` (1rem) is the standard for long-form reading. It must have a line-height of at least 1.6 to ensure the "Digital Paper" feel. -- **Labels (Inter)**: Use `label-md` in all-caps with a `0.05rem` letter-spacing for metadata (e.g., "READING TIME," "DATE SAVED"). This creates a stark, functional contrast to the fluid Serif body text. +- **Labels (Inter)**: (`--font-label`) Use `label-md` in all-caps with a `0.05rem` letter-spacing for metadata (e.g., "READING TIME," "DATE SAVED"). This creates a stark, functional contrast to the fluid Serif body text. --- diff --git a/frontend/docs/domain.md b/frontend/docs/domain.md new file mode 100644 index 0000000..a3f5719 --- /dev/null +++ b/frontend/docs/domain.md @@ -0,0 +1,9 @@ +# Language Learning - Domain Concpts + +Language learning depends on two complementary processes: **exposure** (encountering words in real context) and **retrieval practice** (actively recalling what you have learned). This application uses flashcards as the retrieval primitive — the mechanism by which a word moves from "I have seen this" to "I know this". + +Every flashcard in the system is anchored to a **sense**: a specific meaning of a word in the target language. This matters because languages are full of homonyms and polysemes. A learner who adds the French word *banque* to their word bank needs to know they are learning *bank (financial institution)*, not just the string of letters "banque". The sense link is what gives a flashcard its precision and what allows the system to build fluency models at the word-meaning level over time. + +**For users**, the manual flashcard creator is the most direct route into the system: type a word, find its meaning in the dictionary, confirm it, and a two-sided card is created — one side prompting recognition (see the French word, recall the English meaning), the other prompting production (see the English meaning, produce the French word). The dictionary integration is what elevates this above a simple note-taking tool: it ties the card to a structured sense record, enabling future features like spaced repetition scheduling, fluency tracking, and cross-card grouping by topic or grammar class. + +**For admins**, the WordBankPack CMS is the content pipeline. A pack is a curated, pre-linked set of words — "100 Most Common French Verbs", "Food and Drink Vocabulary" — that users can adopt wholesale into their own word bank. The quality of the sense-linking in a pack directly determines whether a user's flashcards are useful: an entry without a sense link cannot generate flashcards. The admin interface therefore needs dictionary search as a first-class feature, not an afterthought. Flashcard templates attached to pack entries define the *canonical* prompt/answer text for that word, which can be pushed down to users' individual cards as the pack evolves.