Chapter 3: Taking an app from concept to code

Introduction

This chapter introduces planning and design as essential work and previews an end-to-end process for turning an app concept into Streamlit code.

• Planning and design value: Explain why understanding the problem and designing an app before coding are productive parts of real-world app development, rather than wasted time.
  Why it matters: Thoughtful planning and design help produce a better end product before implementation begins.
• Concept-to-code chapter process: Trace the chapter's proposed path from an app concept to requirements, a user-experience-driven design and code organization, and finally code and logic using common Streamlit widgets.
  Why it matters: This path provides a practical structure for developing an app from an idea through implementation.
• Chapter code resources: State that the book's GitHub repository includes a chapter_03 folder containing the chapter's code and in-progress versions for following along.
  Why it matters: The repository gives readers working and intermediate code versions to consult while following the chapter.

Key terms: planning, design, end-to-end experience, real-world app development, app concept, requirements, user experience, code organization, logic, Streamlit widgets

3.1 Concept to code: A six-step process

This section introduces a scalable six-step workflow for turning an app idea into working code without jumping straight into implementation.

• Six-step development workflow: Describe the six steps for developing an app: state the concept, define requirements, visualize the user experience, brainstorm implementation, write code, and iterate.
  Why it matters: This workflow breaks an overwhelming software idea into manageable decisions and actions.
• Requirements and scope boundaries: Explain that defining requirements refines a high-level concept into specific app behavior and explicitly establishes both what the app will do and what it will not do.
  Why it matters: Clear scope prevents a vague concept from expanding into an unmanageable app.
• Scaled planning process: Explain that the same six-step process can be scaled to fit the project: large projects may require substantial time and agreement, while small apps can use quick requirement bullets and simple sketches.
  Why it matters: You can gain the benefits of deliberate planning without treating a small app like a large enterprise project.

Key terms: state the concept, define the requirements, visualize the user experience, brainstorm implementation, write code, iterate, concept, requirements, scope, what the app will do

3.2 Stating our concept: A unit converter

This section states the unit-converter app’s concise concept and explains why a clear, revisable concept guides development and communication.

• Unit converter concept: State the app concept as a Streamlit app that lets users convert between different units of measurement.
  Why it matters: A concise concept gives the project a clear problem to solve before details and implementation decisions are added.
• Concept statement purpose: Explain how stating a concept focuses development on the core problem, can be revised when a better-fitting idea emerges, and provides a short description to communicate the work to others.
  Why it matters: A focused concept helps prevent scope from drifting while making it easier for potential users and collaborators to understand the project.

Key terms: concept, Streamlit app, units of measurement, stating the concept, core, one-line description

3.3 Defining the requirements

This section turns the unit-converter concept into stakeholder-focused, technology-agnostic requirements that guide its design and implementation.

• Requirement definition principles: Explain that requirements state concrete capabilities an app should provide for stakeholders and avoid implementation or technology language.
  Why it matters: Clear, technology-neutral requirements let developers choose an implementation that fulfills actual stakeholder needs.
• Unit converter functional requirements: Describe the unit converter's required behavior: users enter a numeric quantity and from-unit, choose a compatible to-unit, and receive the converted value, including metric, imperial, and cross-system conversions.
  Why it matters: These requirements define the user-visible behavior the unit converter must deliver.
• Stakeholder and maintainability needs: Describe how requirements can come from users and other stakeholders, including the requirement that adding units or quantities be straightforward so developers or maintainers spend less time on common change requests.
  Why it matters: Considering maintainers and organizational stakeholders prevents an app from serving users while becoming unnecessarily costly to change or operate.

Key terms: requirements, stakeholders, implementation language, numeric quantity, from-unit, to-unit, imperial, metric, developer, maintainer

3.3.1 Defining what the app won’t do

This section defines the unit converter’s out-of-scope features and explains how explicit scope supports prioritization, future phasing, and stakeholder discussion.

• Explicit out-of-scope definition: Explain why an app plan should state what it will not do as well as its requirements. Describe how this prevents users or collaborators from assuming unplanned features are included.
  Why it matters: Clear boundaries turn assumed features into an explicit conversation before they create confusion or extra work.
• Unit converter exclusions: State the specific functionality excluded from the chapter’s unit conversion app: usage tracking, logging, unrelated visualizations, and conversions without a simple constant conversion factor such as currencies. Explain that the app is deliberately kept simple to focus on learning Streamlit.
  Why it matters: Limiting the example keeps attention on the Streamlit fundamentals rather than unrelated product and integration complexity.
• Scope-driven prioritization: Describe how an out-of-scope list helps prioritize the current version and phase possible features into a future version. Explain that documenting scope can elicit stakeholder feedback and start a prioritization conversation.
  Why it matters: A feature deferred today can be intentionally revisited later instead of becoming an unexamined expectation.

Key terms: requirements, scope, out of scope, stakeholders, usage tracking, logging, visualizations, constant conversion factor, currencies, exchange rate

3.4 Visualizing the user experience

This section introduces designing an app by working backward from the intended user experience before implementing it.

• User-experience-first design: Explain the approach of working backward from the user experience when beginning an app design, rather than starting immediately with code or implementation details.
  Why it matters: Beginning with the experience helps keep the app centered on what users need to accomplish.
• Benefits of user-centered planning: Describe how starting with the user experience supports end-product quality by addressing user needs and preferences and by revealing usability problems early.
  Why it matters: Finding user-experience issues before implementation can prevent a polished-looking app from being difficult to use.
• Alternative development starting points: Distinguish the user-experience-first approach from other valid ways of beginning development: coding top to bottom, planning app components and their connections, or tackling the hardest problem first.
  Why it matters: Recognizing alternatives clarifies that user-experience-first design is a chosen approach, not the only possible workflow.

Key terms: user experience, working backwards, end-product quality, user needs, user preferences, usability problems, components, design, hardest part of the problem

3.4.1 Creating a mock

This subsection creates a preliminary user-interface mock-up for the unit converter and uses it to prioritize the desired user experience before implementation details.

• Unit converter mock-up: Describe the preliminary unit-converter interface shown in the mock-up, including its inputs, controls, and displayed result. Explain how a user selects a category, enters a numeric value, chooses compatible source and destination units, clicks Convert, and sees the converted value.
  Why it matters: A concrete mock-up turns written requirements into a user experience that can guide implementation.
• User-centered mock design: Explain why the mock-up should depict the desired end-user experience rather than be elaborate or final. State that it can be made with simple tools, may change during implementation, and should not initially be constrained by assumptions about Streamlit's available elements.
  Why it matters: Starting from the ideal experience helps prevent the framework's current feature set from prematurely narrowing the design.

Key terms: mock-up, UI, unit category selector, select box, Convert button, drop-down menus, user experience, UI design, Streamlit, implementation

3.5 Brainstorming the implementation

This section begins implementation planning by identifying the app’s frontend and backend and how information moves between them.

• Implementation planning purpose: Explain that brainstorming the implementation means listing the parts of the solution, deciding how they fit together, and mapping the app’s flow of thinking so the planned user experience can be built.
  Why it matters: This planning step turns a user-facing idea into a workable design for code.
• Frontend and backend roles: Distinguish the frontend from the backend: the frontend collects user input and displays output, while the backend processes that input and returns output for the frontend to display.
  Why it matters: Separating interaction and processing clarifies how an app turns a user action into a visible result.
• UI translation to Streamlit: Describe that the previously envisioned frontend UI must be translated into corresponding Streamlit elements during the later code walkthrough, while backend planning begins with the unit conversion itself.
  Why it matters: A mockup becomes an app only when its interface and its processing are expressed in the appropriate code components.

Key terms: brainstorming the implementation, flow of thinking, solution, frontend, backend, inputs, outputs, UI, Streamlit elements, unit conversion

3.5.1 Converting units

This section derives a scalable method for converting between units by storing each unit’s factor to a shared standard unit.

• Direct conversion factors: Explain how a conversion factor converts a value from unit X to unit Y by multiplication, and how to derive the reverse conversion factor by dividing 1 by the original factor.
  Why it matters: Direct and reverse factors provide the arithmetic foundation for every unit conversion in the app.
• Standard-unit conversion strategy: Describe why storing a factor for every pair of units does not scale, and trace the two-step conversion through a category’s standard unit: convert X to standard unit S, then use the reciprocal of Y-to-S to convert S to Y.
  Why it matters: Using one shared intermediate unit keeps the app’s conversion data manageable while still allowing any supported units to be converted.

Key terms: conversion factor, reverse conversion factor, X-to-Y conversion factor, standard unit, standard intermediate unit, X-to-S conversion factor, Y-to-S conversion factor, conversion factors

3.5.2 Tracking units and conversion factors

This section explains how to make the unit converter easy to maintain by centralizing unit definitions and conversion factors in one configuration file.

• Maintainable unit configuration: Explain why straightforward addition of units is a non-user requirement and why it matters to developers maintaining the unit converter after launch.
  Why it matters: Designing for maintenance reduces the time and risk involved in responding to future feature requests and bug fixes.
• Single source unit definitions: Describe the recommended master configuration file: it contains all quantities, units, and conversion factors, provides one obvious place to add a unit, and uses a format where a new unit can be appended in a few lines.
  Why it matters: A single source of unit information makes common changes predictable and quick.
• Configuration-driven application code: Explain that the configuration file must be the only file referring to specific quantities or units, so UI and other application code pull that information from the configuration rather than hard-coding it.
  Why it matters: Keeping specific unit knowledge out of application code prevents a new unit or quantity from triggering scattered, error-prone changes.

Key terms: non-user requirement, maintenance, adding new units, master list, configuration file, quantities, units, conversion factors, hard-coded, UI code

3.5.3 Mapping the flow of logic

This section maps how configuration, frontend controls, and backend conversion logic work together in the unit converter app.

• Configuration-driven unit selection: Describe how the configuration file supplies the quantity-selector radio buttons and determines which From Unit and To Unit options appear after a quantity is selected.
  Why it matters: This explains how the app keeps its unit choices and conversion setup connected rather than hardcoding each interface option.
• Conversion request and response flow: Trace the conversion flow from user input to displayed result: the user selects From and To units and clicks Convert, the frontend sends those entries to the backend, and the backend uses configuration conversion factors for the two-step conversion before returning the value for display.
  Why it matters: This end-to-end flow provides the blueprint for separating the app interface from the calculation logic.

Key terms: configuration file, quantity-selector radio buttons, From Unit, To Unit, drop down menus, Convert button, frontend, backend, conversion factors, two-step conversion

3.6 Writing code

This section introduces the implementation sequence for the unit converter: build a dummy Streamlit frontend, implement a contract-driven backend, and connect the two.

• Implementation sequence: Describe the planned order for coding the app: create a dummy frontend, implement the backend and logic flow, define their contract, and wire the frontend to call the backend.
  Why it matters: A staged implementation approach makes it easier to turn an app design into a working application.
• Dummy Streamlit frontend: Explain that the initial frontend is a dummy interface used to learn the Streamlit widgets that make the app UI possible.
  Why it matters: Starting with a simple interface lets you establish the user-facing controls before the underlying behavior is complete.
• Frontend-backend contract: Explain that a contract, or API, is defined between the frontend and backend, and that the backend must fulfill that contract when the frontend makes calls.
  Why it matters: A clear contract gives the UI and application logic a defined way to communicate.
• Backend configuration start: State that backend implementation begins with the configuration file before implementing the backend and the planned logic flow.
  Why it matters: The configuration file is identified as the starting point for organizing the backend implementation.

Key terms: dummy frontend, backend, logic flow, frontend, wiring up, Streamlit widgets, UI, contract, API, backend calls

3.6.1 Implementing the frontend

This section builds the Unit Converter’s nonfunctional Streamlit frontend incrementally, capturing user choices and arranging them to match the UI mock.

• Incremental frontend setup: Describe how to create and run frontend.py as a Streamlit app, then iteratively rerun it in the browser while adding UI elements. State that this stage uses hardcoded placeholder choices because the backend is not available yet.
  Why it matters: Building and checking the interface in small steps makes it possible to verify the user experience before connecting application logic.
• Input widget selection: Explain how the Unit Converter captures its inputs with Streamlit widgets: st.radio selects one quantity, st.text_input collects the value as a string that is cast to float, and two st.selectbox widgets select From and To units. Describe how the second selectbox uses index=1 so the two unit selectors initially differ.
  Why it matters: Correctly capturing each user choice gives the later conversion logic the inputs it needs.
• Sidebar and column layout: Describe how st.sidebar places the quantity radio buttons in the left sidebar and how st.columns(2) creates side-by-side containers for the From and To selectboxes. Distinguish the with context-manager form from dot notation: use a context manager for multiple elements in a container, and dot notation for one element or for displaying items out of order.
  Why it matters: Containers let the app’s layout match the intended user experience instead of placing every element in one vertical sequence.
• Dummy conversion trigger: State that st.title identifies the app and st.button("Convert") adds the future conversion trigger, but its click block contains pass at this point, so the finished frontend is only a dummy interface and performs no conversion.
  Why it matters: Separating the visible controls from unfinished behavior prepares the app to be connected to conversion logic next.

Key terms: frontend.py, streamlit run, Rerun, Always Rerun, hardcoding, backend, st.radio, st.text_input, float, st.selectbox

3.6.2 Implementing the backend

This section models unit-conversion configuration with dataclasses and implements a separated backend API for listing quantities and units and converting values.

• Unit conversion configuration model: Describe how the app represents supported quantities and units using the Unit and Quantity dataclasses and the unit_config dictionary. Explain that quantity and unit names are dictionary keys, while a Unit stores its abbreviation and conversion factor relative to the quantity’s standard unit.
  Why it matters: A structured configuration makes supported units easy to look up and extend without changing the conversion logic.
• Frontend-backend API contract: Explain the backend API as a contract separating frontend and backend responsibilities. State its three actions: list-quantities, list-units for a selected quantity, and convert-value for a value and selected units.
  Why it matters: A stable API lets the frontend and backend change independently as long as they continue to honor the same contract.
• Backend conversion operations: Trace how the backend functions implement list-quantities, list-units, and convert-value from unit_config. Explain that conversion first multiplies by the source unit’s value_in_std_units to reach standard units, then divides by the target unit’s factor, returning a Result that includes the converted value and the relevant Unit objects.
  Why it matters: These functions turn the app’s configuration and API contract into the actual behavior the frontend can use.

Key terms: Unit, Quantity, unit_config, std_unit, value_in_std_units, dataclass, separation of concerns, API, frontend, backend

3.6.3 Wiring up the frontend and backend

This section connects the Unit Converter frontend to backend functions so widget choices are dynamic, conversion runs on demand, and results appear as side-by-side metrics.

• Dynamic quantity and unit options: Describe how the frontend replaces hard-coded quantity and unit lists with backend calls: list_quantities for the quantity radio button and list_units with the selected quantity for both unit dropdowns.
  Why it matters: Connecting widget options to backend data makes the interface respond correctly when the user selects a different kind of quantity.
• Conversion result presentation: Explain how clicking Convert calls convert_value with the selected quantity, source unit, target unit, and input value, then displays the returned Result object's values and unit abbreviations using two side-by-side st.metric elements with no delta.
  Why it matters: This completes the app's main user flow by turning user inputs into a clearly presented conversion result.

Key terms: list_quantities, list_units, quantity selector, From unit, To unit, convert_value, Result, from_value, to_value, from_unit

3.7 Iterating on the app

This section introduces post-launch iteration, using user feedback to identify and improve usability issues in a working app.

• User-feedback-driven iteration: Explain why launching a functional app is the start of its real-world journey and how user feedback can guide subsequent improvements. Describe how users’ experience and opinions can expose usability problems or testing blind spots.
  Why it matters: Real users can reveal problems that are not apparent while you are building or testing the app yourself.

Key terms: user feedback, usability problems, blind spots, iteration

3.7.1 Rounding conversion results

This section improves the Unit Converter’s result display by formatting large numbers and making result rounding an optional user-controlled feature.

• Result formatting behavior: Describe how the format_value function formats a converted value with thousands separators and optionally rounds it to a supplied number of decimal places. Explain that omitting decimal_places leaves the value unrounded.
  Why it matters: Readable, appropriately precise results make a conversion app easier for users to interpret.
• Decimal places numeric input: Explain how st.number_input collects the preferred number of decimal places, including its default of 3 and minimum of 0. Distinguish why it fits a small integer precision setting but st.text_input remains preferable for the virtually unbounded value being converted.
  Why it matters: Choosing an input widget that matches the kind and range of data prevents awkward interactions and invalid input.
• Optional rounding control: Describe how an unchecked-by-default st.checkbox makes rounding optional: places is initialized to None, and the numeric decimal-place input is shown and assigned only when the user checks Round Results?. Explain why the initial None assignment is needed outside the conditional block.
  Why it matters: Conditional controls reduce cognitive load while ensuring later code has a valid value whether or not the option is enabled.

Key terms: format_value, decimal_places, is_rounded, round, format, from_display, st.number_input, value, min_value, step

3.7.2 Getting rid of the button

This subsection simplifies the unit converter by removing its Convert button so results update immediately as inputs change, reinforcing the value of iterative user-experience refinement.

• Buttonless conversion flow: Describe how to remove the Convert button from the unit converter by deleting the `if st.button("Convert"):` line and moving its block’s conversion and display code outside the conditional.
  Why it matters: Removing an unnecessary explicit action makes the app respond directly to the values users enter.
• Immediate input-based results: Explain why the Convert button is unnecessary: it only triggers a conversion that can instead always be shown from the current inputs, giving users an immediate result when they change the value or decimal places.
  Why it matters: Showing results as inputs change creates a simpler and more intuitive conversion experience.
• Requirements-driven UX refinement: State that developing an app involves more than writing code: requirements and the design and refinement of the user experience are equally important, including when responding to stakeholder needs.
  Why it matters: A technically working app can still be improved by simplifying its flow around what users need.

Key terms: Convert button, st.button, frontend.py, conversion, inputs, decimal places, rounded output, requirements, user experience, stakeholders

3.8 Summary

This summary recaps a six-step process for turning a Streamlit app concept into a working, iteratively improved app, along with key design and UI-building practices.