frontend-platform documentation

Description

Upgrade Guides

  • frontend-auth -> frontend-platform/auth

  • frontend-logging -> logging

  • frontend-analytics -> frontend-platform/analytics

  • frontend-i18n -> frontend-platform/i18n

  • “Why Upgrade?” summary

API Documentation

We want to use JSDoc to document the actual interfaces and have the API.md file generated.

  • analytics

  • auth

  • i18n

  • logging

  • react

  • top level

Implementation docs

This doc should be specific to the details of the implementation itself. It may be sparse if there's nothing particularly interesting to say beyond the API docs.

  • NewRelicLoggingService

  • SegmentAnalyticsService

  • react-intl i18n service (not a formal impl)

  • axios JWT auth service (not a formal impl)

Frontend principles doc

Want to coordinate writing this with Nimisha, as she’s writing a broader “principles” doc.

Meeting notes:

These are the ones that apply to what edX needs right now

Backend Principles

  1. SOLID -> Extensible Core (Plugins into Core)

  2. Reactive Manifesto + SCS (Self Contained Systems) -> Messaging + Eventing, Async, -> Resiliency + Availability

  3. Domain-Driven Design -> Core vs. not, Boundaries, Ubiquitous Language, Business Model

  4. Keep it Simple

Frontend Principles

  • SOLID - single responsibility, Interface Segregation, Dependency Injection (of config, libraries)

    • some libraries are agnostic to framework (ex., react, redux, etc.)

      • Apps are tied to framework

    • prefer dependency injection over peer dependencies

  • Sensible defaults with optional configuration

    • “Convention” over configuration

  • Independent configuration of frontend

    • Simplicity over dryness

  • Keep it simple

    • Right tool for the job and for that data

      • example: Do you really need redux?

  • frontend-base responsibility

  • Uni-directional Data flow + data immutability (this is the way of react/redux)

    • Watch out for over-use of pub/sub or outside ways of passing data around, singletons, etc.

    • isolation of side effects

  • Utility-first CSS over semantic CSS class names

  • Components reusable for a particular purpose, not reusable for many purposes

  • Single source of truth in frontend data management

    • In redux store vs. component state, not both

  • Domain-based folders -> modularity

  • Meaningful + intentional tests -> (look at Testing Principles arch FED wiki)

Principles Open Questions

a. MFE boundary factors
-> visual consistency
-> Dev efficiency
- test time
- org structure
- simplicity
- Too many teams in one repo vs. one team working in many repos
-> user navigation
b. Static apps build vs. Server (served)

Fixed

Epic Link

Story Points

None

Assignee

David Joy

Reporter

David Joy

Labels

None

Sprint