How asabeneh/speaksuomi works
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 index.html · README.md README.md · README.html README.html · QUIZ.md QUIZ.md
Components 14
Browser runtime
Static site and client-side quiz logic that run in the browser.
- index.html · Main static entrypoint containing layout, styling, learning content, and quiz script.
index.html - Page UI · Visible navigation and learning-page structure rendered from the HTML document.
- Quiz UI · Visible placement-test interface where learners answer questions and see feedback.
- Scoring engine · Browser-side logic that reads items, scores responses, and maps results to CEFR bands.
- CEFR bands · 0–25 A1, 26–50 A2, 51–75 B1, 76–100 B2 feedback mapping.
- Static host · 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 · A1 to B2 progression that organizes the learning material.
- Grammar notes · Grammar ladder and explanatory notes embedded in the site.
- Vocab & reading · Vocabulary and reading passages presented as static learning resources.
- Hidden tables · Embedded assessment tables in the HTML that define quiz items and correct answers.
Docs
Maintenance and contribution guidance for the repository.
- README.md · High-level description of the site and quiz.
README.md - README.html · Static companion artifact for the repository overview.
README.html - QUIZ.md · Technical notes for the placement quiz and its content model.
docs/QUIZ.md - CONTRIBUTING.md · Instructions for maintaining and editing assessment items.
CONTRIBUTING.md
Connections 16
- 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.