# asabeneh/speaksuomi architecture

> Architecture diagram of the GitHub repository asabeneh/speaksuomi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asabeneh/speaksuomi
- Repository: https://github.com/asabeneh/speaksuomi

## Overview

1. **Overall shape**  
   Finnish Flow is a **static, browser-run, single-page learning site**. There is no backend, API layer, database, build pipeline, or authentication flow in the repository as shown.

2. **Primary runtime artifact**  
   The entire user-facing application lives in **`index.html`**. That file combines:
   - page structure and navigation
   - all styling
   - the learning content
   - the interactive placement quiz script

3. **Content subsystem**  
   The site is primarily a **content-rich learning resource for Finnish** aimed at English speakers. The material is organized as:
   - roadmap from **A1 to B2**
   - grammar notes / grammar ladder
   - vocabulary and reading passages
   - a placement-test section
   This content is served directly from the static HTML rather than loaded from external content services.

4. **Interactive quiz subsystem**  
   The most dynamic part is the **placement quiz** embedded in `index.html`. It is a client-side feature with about **50 items**, and it is the only meaningful runtime logic in the repo.

5. **Quiz data source**  
   The quiz does not appear to fetch data externally. Instead, it **parses hidden assessment tables in the HTML** and uses those as the answer key / item definitions. That means the quiz’s “content model” is encoded in the same document as the UI.

6. **Quiz processing flow**  
   The quiz flow is:
   - user reaches the placement-test section or `#placement-test`
   - the script reads the hidden tables
   - responses are scored in the browser
   - the result is mapped to a CEFR band
   - feedback is displayed to the user  
   The scoring bands are explicitly: **0–25% A1, 26–50% A2, 51–75% B1, 76–100% B2**.

7. **UI boundary**  
   The quiz has a distinct **UI container** separate from the hidden data tables, even though both are in the same file. For architecture diagrams, it helps to treat this as:
   - visible quiz interface
   - hidden content/answer-key layer
   - client-side scoring engine connecting them

8. **Documentation and support files**  
   The repository includes supporting docs that are **non-runtime** but important for maintenance:
   - `README.md` describes the site and quiz at a high level
   - `docs/QUIZ.md` contains technical notes for the quiz
   - `CONTRIBUTING.md` defines how to edit and maintain the assessment items
   - `README.html` is likely a rendered/static companion artifact, not a separate subsystem

9. **Deployment / serving model**  
   The project is intended to be opened directly in a browser or served with a simple static server such as Python’s `http.server`. This implies a **static hosting model**: any web server capable of serving files is sufficient.

10. **Key architectural boundary to draw**  
   The main boundary is between:
   - **static authored content** in `index.html`
   - **client-side quiz logic** running in the browser  
   There are no external service dependencies, so the architecture is essentially a **single-file static SPA with embedded educational content and DOM-driven quiz logic**.

Main entry points: [`index.html`](https://github.com/asabeneh/speaksuomi/blob/master/index.html) (index.html), [`README.md`](https://github.com/asabeneh/speaksuomi/blob/master/README.md) (README.md), [`README.html`](https://github.com/asabeneh/speaksuomi/blob/master/README.html) (README.html), [`docs/QUIZ.md`](https://github.com/asabeneh/speaksuomi/blob/master/docs/QUIZ.md) (QUIZ.md)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser runtime"]
  node_index["index.html<br/>single-page site<br/>[index.html]"]
  node_page_ui["Page UI<br/>static layout"]
  node_placement_ui["Quiz UI<br/>interactive UI"]
  node_quiz_engine{{"Scoring engine<br/>client script"}}
  node_cefr_bands["CEFR bands<br/>result mapping"]
  node_static_host["Static host<br/>serving model"]
end

subgraph group_content["Authored content"]
  node_content_roadmap["Roadmap<br/>learning path"]
  node_content_grammar["Grammar notes<br/>reference content"]
  node_content_vocab["Vocab & reading<br/>learning content"]
  node_hidden_tables["Hidden tables<br/>answer key data"]
end

subgraph group_docs["Docs"]
  node_readme_md["README.md<br/>project overview<br/>[README.md]"]
  node_readme_html["README.html<br/>rendered readme<br/>[README.html]"]
  node_quiz_doc["QUIZ.md<br/>quiz notes<br/>[QUIZ.md]"]
  node_contributing["CONTRIBUTING.md<br/>editor guide<br/>[CONTRIBUTING.md]"]
end

node_index -->|"renders"| node_page_ui
node_index -->|"contains"| node_content_roadmap
node_index -->|"contains"| node_content_grammar
node_index -->|"contains"| node_content_vocab
node_index -->|"hosts"| node_placement_ui
node_index -->|"includes"| node_quiz_engine
node_index -->|"embeds"| node_hidden_tables
node_quiz_engine -->|"reads"| node_hidden_tables
node_quiz_engine -->|"drives"| node_placement_ui
node_quiz_engine -->|"maps to"| node_cefr_bands
node_placement_ui -->|"shows"| node_cefr_bands
node_readme_md -->|"describes"| node_index
node_quiz_doc -->|"documents"| node_quiz_engine
node_contributing -->|"guides"| node_hidden_tables
node_readme_html -.->|"companion"| node_readme_md
node_static_host -->|"serves"| node_index

click node_index "https://github.com/asabeneh/speaksuomi/blob/master/index.html"
click node_readme_md "https://github.com/asabeneh/speaksuomi/blob/master/README.md"
click node_readme_html "https://github.com/asabeneh/speaksuomi/blob/master/README.html"
click node_quiz_doc "https://github.com/asabeneh/speaksuomi/blob/master/docs/QUIZ.md"
click node_contributing "https://github.com/asabeneh/speaksuomi/blob/master/CONTRIBUTING.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_page_ui,node_placement_ui,node_quiz_engine,node_cefr_bands,node_static_host toneBlue
class node_content_roadmap,node_content_grammar,node_content_vocab,node_hidden_tables toneAmber
class node_readme_md,node_readme_html,node_quiz_doc,node_contributing toneMint
```

## Components

### Browser runtime

Static site and client-side quiz logic that run in the browser.

- [index.html](https://github.com/asabeneh/speaksuomi/blob/master/index.html): single-page site · Main static entrypoint containing layout, styling, learning content, and quiz script. · `index.html`
- **Page UI**: static layout · Visible navigation and learning-page structure rendered from the HTML document.
- **Quiz UI**: interactive UI · Visible placement-test interface where learners answer questions and see feedback.
- **Scoring engine**: client script · Browser-side logic that reads items, scores responses, and maps results to CEFR bands.
- **CEFR bands**: result mapping · 0–25 A1, 26–50 A2, 51–75 B1, 76–100 B2 feedback mapping.
- **Static host**: serving model · Any simple file server or direct browser open can serve the site.

### Authored content

Primary learning material and hidden assessment data embedded in the site.

- **Roadmap**: learning path · A1 to B2 progression that organizes the learning material.
- **Grammar notes**: reference content · Grammar ladder and explanatory notes embedded in the site.
- **Vocab & reading**: learning content · Vocabulary and reading passages presented as static learning resources.
- **Hidden tables**: answer key data · Embedded assessment tables in the HTML that define quiz items and correct answers.

### Docs

Maintenance and contribution guidance for the repository.

- [README.md](https://github.com/asabeneh/speaksuomi/blob/master/README.md): project overview · High-level description of the site and quiz. · `README.md`
- [README.html](https://github.com/asabeneh/speaksuomi/blob/master/README.html): rendered readme · Static companion artifact for the repository overview. · `README.html`
- [QUIZ.md](https://github.com/asabeneh/speaksuomi/blob/master/docs/QUIZ.md): quiz notes · Technical notes for the placement quiz and its content model. · `docs/QUIZ.md`
- [CONTRIBUTING.md](https://github.com/asabeneh/speaksuomi/blob/master/CONTRIBUTING.md): editor guide · Instructions for maintaining and editing assessment items. · `CONTRIBUTING.md`

## Connections

- index.html → Page UI: renders · The HTML document provides the page structure and navigation.
- index.html → Roadmap: contains · The learning roadmap is authored directly in the main HTML file.
- index.html → Grammar notes: contains · Grammar explanations are embedded in the static page.
- index.html → Vocab & reading: contains · Vocabulary and reading content live in the same document.
- index.html → Quiz UI: hosts · The placement-test section is part of the page markup.
- index.html → Scoring engine: includes · The only meaningful runtime logic is embedded client-side script.
- index.html → Hidden tables: embeds · Hidden tables in the HTML provide the quiz data and answer key.
- Scoring engine → Hidden tables: reads · The browser script parses the hidden tables to build and score items.
- Scoring engine → Quiz UI: drives · The scoring logic powers the user-facing placement-test interaction.
- Scoring engine → CEFR bands: maps to · Scores are converted into A1/A2/B1/B2 feedback bands.
- Quiz UI → CEFR bands: shows · The interface displays the final placement result to the learner.
- README.md → index.html: describes · README explains the site entrypoint and its purpose.
- QUIZ.md → Scoring engine: documents · Quiz notes explain the browser-side scoring and data model.
- CONTRIBUTING.md → Hidden tables: guides · Contribution instructions focus on editing the embedded assessment items.
- README.html → README.md: companion · Rendered readme mirrors the main project overview.
- Static host → index.html: serves · A simple static server can host the single-page site.
