language-learning-app/frontend/docs/architecture.md

# 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. It is written in TypeScript.

Package management is with pnpm.

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

For "boring" screens (settings pages, admin pages, cms-like pages) use shadcn-svelte components to create sensible defaults and uninteresting User Interfaces.

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.