Visualizing the v3 architecture - feedback wanted

[dillonkearns]

There's a lot to explain in the v3 architecture, and this doesn't address every single detail, but I wanted to try to capture the core details. I'll try to explain it in the format I would use in the documentation site so people can give me feedback and suggestions for how to make it more clear.

Accompanying Explanation

This shows the flow through 3 user interactions:

1. Open Page (go to initial URL in browser)
2. Submit Form (click favorite button)
3. Click Button (click on a non-form button with an onClick)

In (1), we hit the database using our definitions in our custom-backend-task.ts.

In (2), the form makes a POST request to our Backend App. After running the BackendTask in action with the incoming HTTP request, our data is re-fetched from the Frontend App in order to get fresh data from any changes (like a new favorite count).

(3) is a vanilla Elm Msg. It doesn't communicate with the server at all. It directly sends a ToggleMenu Msg, which updates the Model to show the menu.

Route Code

Here is the code for the route. Note that this module is used in two Elm apps - our Backend App (runs on our server) and Frontend App (runs in user's browser).

module Route.Feed exposing (ActionData, Data, Model, Msg, RouteParams, route)

import BackendTask exposing (BackendTask)
import BackendTask.Custom
import Effect
import ErrorPage exposing (ErrorPage)
import FatalError exposing (FatalError)
import Form
import Form.Field
import Form.Validation
import Head
import Html
import Html.Attributes
import Json.Decode as Decode exposing (Decoder)
import Json.Encode as Encode
import PagesMsg exposing (PagesMsg)
import RouteBuilder
import Server.Request
import Server.Response
import Server.Session
import Server.SetCookie
import Shared
import View


type alias Model =
    { showMenu : Bool }


type Msg
    = ToggleMenu


type alias RouteParams =
    {}


route : RouteBuilder.StatefulRoute RouteParams Data ActionData Model Msg
route =
    RouteBuilder.serverRender { data = data, action = action, head = head }
        |> RouteBuilder.buildWithLocalState
            { view = view
            , init = init
            , update = update
            , subscriptions = \_ _ _ _ -> Sub.none
            }


init :
    RouteBuilder.App Data ActionData RouteParams
    -> Shared.Model
    -> ( Model, Effect.Effect Msg )
init app shared =
    ( { showMenu = False }, Effect.none )


update :
    RouteBuilder.App Data ActionData RouteParams
    -> Shared.Model
    -> Msg
    -> Model
    -> ( Model, Effect.Effect Msg )
update app shared msg model =
    case msg of
        ToggleMenu ->
            ( { model | showMenu = not model.showMenu }, Effect.none )


type alias Data =
    { user : User
    , posts : List Post
    }


type alias ActionData =
    {}


data :
    RouteParams
    -> Server.Request.Parser (BackendTask.BackendTask FatalError.FatalError (Server.Response.Response Data ErrorPage.ErrorPage))
data routeParams =
    Server.Request.succeed ()
        |> Server.Session.withSession
            { name = "session"
            , options = Server.SetCookie.initOptions
            , secrets = BackendTask.succeed [ "my-secret" ]
            }
            (\() sessionResult ->
                BackendTask.map2 Data
                    (getUser sessionResult)
                    (BackendTask.Custom.run "getPosts" Encode.null postsDecoder |> BackendTask.allowFatal)
                    |> BackendTask.map Server.Response.render
                    |> BackendTask.map (Tuple.pair (sessionResult |> Result.withDefault Server.Session.empty))
            )


head : RouteBuilder.App Data ActionData RouteParams -> List Head.Tag
head app =
    []


view :
    RouteBuilder.App Data ActionData RouteParams
    -> Shared.Model
    -> Model
    -> View.View (PagesMsg Msg)
view app shared model =
    { title = "Feed"
    , body =
        [ navbarView app.data.user ToggleMenu model.showMenu
        , postsView app
        ]
    }


postsView app =
    app.data.posts
        |> List.map (\post -> favoriteFormView app post)
        |> Html.div []


action :
    RouteParams
    -> Server.Request.Parser (BackendTask FatalError (Server.Response.Response ActionData ErrorPage))
action routeParams =
    formHandlers
        |> Server.Request.formData
        |> Server.Request.map
            (\( _, parsedForm ) ->
                case parsedForm of
                    Ok (ToggleFavorite validatedForm) ->
                        validatedForm.setFavorite
                            |> toggleFavorite
                            |> BackendTask.map (\() -> Server.Response.render {})

                    Err error ->
                        BackendTask.succeed (Server.Response.render {})
            )


toggleFavoriteForm : Form.HtmlForm String ToggleFavoriteForm Bool Msg
toggleFavoriteForm =
    (\setFavorite ->
        { combine =
            ToggleFavoriteForm
                |> Form.Validation.succeed
                |> Form.Validation.andMap setFavorite
        , view =
            \formState -> [ favoriteButton formState ]
        }
    )
        |> Form.init
        |> Form.hiddenKind ( "kind", "regular" ) "Expected kind."
        |> Form.hiddenField "set-favorite" Form.Field.checkbox


type Action
    = ToggleFavorite ToggleFavoriteForm


type alias ToggleFavoriteForm =
    { setFavorite : Bool }


formHandlers : Form.ServerForms String Action
formHandlers =
    Form.initCombined ToggleFavorite toggleFavoriteForm

[sylbru]

I guess what might help would be, in addition to what you already have, three separate diagrams highlighting the relevant bits, and three code blocks showing only the relevant functions and types. As is, the diagram and the code might feel a bit daunting at first sight.

I would also, but maybe that’s just me, rearrange the three actions like this:

1. Open Page; but also explaining that it can be server-rendered or statically generated
2. Click Button (emphasizing the fact that you can very easily put your regular Elm app in there, while benefitting from SEO stuff)
3. Submit Form (probably more advanced stuff)

But mostly, separating diagrams and code blocks in three, demonstrating each of these three actions (maybe interactively by the way?) would be awesome, I think.

[dillonkearns]

Great idea to split it into 3 separate examples! And maybe separate things into different relevant code snippets so I don't have to reveal those all at once. I'll give that a try!