A user interface usually shows the result of an action, but rarely everything that happens behind it.
Clicking a login button can trigger several security checks. An API request can involve validation, data transformation, and error handling. An electronic invoice can contain structured data that remains invisible in its PDF representation.
Technical documentation is useful for understanding these mechanisms, but it does not always make the sequence of operations easy to follow.
Another approach is to represent these processes through interactive experiences.
Users trigger an action, observe the different stages, and progressively discover the underlying technical mechanisms.
This article presents the architecture of a collection of six interactive experiences built with native HTML, CSS, and JavaScript, without a frontend framework.
1. Making Invisible Processes Visible
Consider a simple example: authentication.
From the user's perspective, the process may consist of three actions:
Enter credentials
│
â–¼
Click "Log in"
│
â–¼
Access the application
From the system's perspective, the same operation can involve several additional mechanisms:
Authentication request
│
â–¼
Input validation
│
â–¼
Credential verification
│
â–¼
Security checks
│
â–¼
Session creation or renewal
│
â–¼
Response to the user
The purpose of an interactive experience is to make these stages understandable without requiring users to study the entire architecture beforehand.
The objective is not necessarily to reproduce a real system, but to represent the operations that may be involved in its execution.
This distinction makes it possible to create lightweight simulations while maintaining technical accuracy.
2. A Frontend Architecture Without a Framework
The experiences rely on three native browser technologies:
| Technology | Responsibility |
|---|---|
| HTML | Experience structure and content |
| CSS | Presentation and visual states |
| JavaScript | Interactions and progression logic |
The project does not require a frontend framework.
Each experience has its own interface and interactive logic while sharing a common visual foundation.
The documented project structure is:
interactive-experiences/
│
├── README.md
├── LICENSE
│
├── assets/
│ └── interactive.css
│
├── fr/
│ ├── cookies.html
│ ├── automatisation.html
│ ├── securite.html
│ ├── facturx.html
│ ├── from-scratch.html
│ └── api-interactive.html
│
└── en/
├── cookies.html
├── automation.html
├── security.html
├── facturx.html
├── from-scratch.html
└── api-interactive.html
This organization separates experiences and languages while sharing the visual presentation layer.
The public documentation describes the project architecture but does not distribute production files.
3. Representing an Experience as a Sequence of States
An interactive experience can be modeled as a sequence of states.
Each state represents a stage of the process being examined.
For example, an API request simulation could follow this progression:
Initial state
│
â–¼
Request sent
│
â–¼
Data validated
│
â–¼
Processing completed
│
â–¼
Response received
A simplified JavaScript representation could look like this:
const steps = [
{
id: "request",
title: "Sending the request",
description: "The client transmits the data."
},
{
id: "validation",
title: "Validation",
description: "The server validates the data."
},
{
id: "processing",
title: "Processing",
description: "Business logic is executed."
},
{
id: "response",
title: "Response",
description: "The server returns a result."
}
];
This structure describes the stages independently of their visual representation.
A function can then display the current stage:
let currentStep = 0;
function renderStep() {
const step = steps[currentStep];
document.querySelector("#step-title").textContent =
step.title;
document.querySelector("#step-description").textContent =
step.description;
}
A button allows the user to move to the next stage:
document.querySelector("#next")
.addEventListener("click", () => {
if (currentStep < steps.length - 1) {
currentStep++;
renderStep();
}
});
renderStep();
This is an educational example. It illustrates one way to build an interactive sequence with vanilla JavaScript without reproducing the production code of the experiences.
The benefit of this approach is that explanatory content, application state, and interface rendering remain separate.
4. From Scratch vs. Prebuilt: Visualizing Architectural Trade-Offs
The first experience compares two ways of addressing the same requirement: building a system from native components or using a prebuilt solution.
Both approaches can produce comparable functional results, but they distribute complexity differently.
Same requirement
│
├── Custom implementation
│ ├── Component selection
│ ├── Rule implementation
│ └── Direct maintenance
│
└── Prebuilt solution
├── Existing features
├── Configuration
└── Adaptation to constraints
An interactive experience makes it possible to compare these two paths while progressively revealing their implications.
| Criterion | Custom implementation | Prebuilt solution |
|---|---|---|
| Initial work | Build the system | Existing functionality |
| Architecture | Component selection | Existing structure |
| Evolution | Direct adaptation | Available extensions |
| Maintenance | Internal ownership | Dependency maintenance |
The objective is not to present one approach as universally superior to the other.
A prebuilt solution can significantly reduce development time. A custom implementation can provide greater architectural freedom when requirements are specific.
In both cases, complexity exists. It is simply distributed across different parts of the system.
5. APIs and Integration: Following a Request Between Two Systems
An API is often introduced through a short example:
const response = await fetch("/api/example");
const data = await response.json();
However, these two lines can hide a much larger sequence of operations.
Client
│
├── Request construction
├── Data transmission
│
â–¼
Server
│
├── Authentication, if required
├── Validation
├── Authorization
├── Business logic
│
â–¼
HTTP response
│
├── Status code
├── Response data
└── Error handling
The API and integration experience allows users to follow this type of sequence and understand the operations that may occur between two systems.
Introducing Alternative Paths
A technical process does not always follow a linear path.
A request may be rejected, contain invalid data, or fail during processing.
A simulation can represent these situations through different branches:
Request received
│
â–¼
Valid data?
│
├── No → HTTP 400
│
└── Yes
│
â–¼
Processing
│
├── Failure → HTTP 500
│
└── Success → HTTP 200
The HTTP status codes shown here are generic examples.
Their actual use depends on the nature of the request and the error encountered.
This representation demonstrates that integration is not simply about transmitting data. It also requires defining how systems behave when operations do not proceed as expected.
6. Automation: Breaking a Task Into Technical Operations
An automated task may appear simple when described by its result.
For example:
Automatically generate a document
A real implementation, however, may require several operations:
Retrieve data
│
â–¼
Validate information
│
â–¼
Apply business rules
│
â–¼
Generate the document
│
â–¼
Verify the result
│
â–¼
Store or transmit
The automation experience exposes the difference between the visible task and the process required to execute it.
An interactive scenario can also demonstrate what happens when a condition is not satisfied.
function validateInput(data) {
if (!data.reference) {
return {
valid: false,
reason: "Missing reference"
};
}
return {
valid: true
};
}
This example illustrates a basic validation rule.
In a real system, the rules may be considerably more extensive and depend on the business context.
The educational objective is to demonstrate that automation is not simply about replacing a manual action with a script.
It requires formalizing execution conditions, validation rules, possible errors, and expected results.
7. Application Security: The Mechanisms Behind Authentication
A login interface generally consists of a few input fields and a button.
However, application security depends on mechanisms that are not directly visible in that interface.
An interactive experience can represent several layers of security controls.
| Mechanism | Responsibility |
|---|---|
| Validation | Check incoming data |
| Authentication | Verify credentials |
| Rate limiting | Reduce abusive attempts |
| Session | Maintain an authenticated state |
| Authorization | Control access to resources |
The application security experience reveals the checks that may occur behind an authentication process.
Authentication vs. Authorization
These two concepts are often confused.
Authentication answers the question:
Who is the user?
Authorization answers a different question:
Which operations can the user perform?
A successfully authenticated user should not necessarily have access to every application resource.
An interactive representation makes this distinction visible by separating the stages.
Identity verified
│
â–¼
Resource requested
│
â–¼
Sufficient permissions?
│
├── No → Access denied
│
└── Yes → Access granted
This is an educational representation.
A simulation running in the browser does not replace the server-side security controls required in a real application.
8. Cookies and Personal Data: Representing Invisible Exchanges
Accepting a cookie is a simple action from the user's perspective.
However, the associated mechanisms can vary considerably depending on the type of cookie, its purpose, and the services involved.
A cookie can maintain a session, remember a preference, or associate multiple interactions with an identifier.
The cookies and personal data experience allows users to follow what may happen after accepting cookies, particularly when data collection, analysis, or profiling mechanisms are involved.
A conceptual sequence can be represented as:
User action
│
â–¼
Cookie or identifier
│
â–¼
Association with interactions
│
â–¼
Potential analysis
│
â–¼
Potential profiling
This sequence does not mean that every cookie automatically triggers these operations.
The purposes, collected information, and processing activities depend on the actual implementation.
Separating Storage From Processing
A cookie does not necessarily contain a complete profile.
It may contain an identifier that allows a system to retrieve information stored elsewhere.
For example:
Browser cookie
│
└── Identifier: example-042
│
â–¼
Remote system
│
└── Associated data
This distinction helps explain why the size or visible content of a cookie is not sufficient to determine the extent of a data processing operation.
The experience represents these mechanisms without needing to perform actual user profiling.
9. Factur-X: Exploring the Two Representations of an Invoice
A Factur-X invoice provides another example of a technical mechanism that remains largely invisible to the user.
The document combines a human-readable PDF/A-3 representation with an embedded XML file containing structured invoice data.
Factur-X invoice
│
├── PDF/A-3
│ └── Human-readable representation
│
└── Embedded XML
└── Structured invoice data
The Factur-X experience allows users to explore this dual representation and understand why the information must remain consistent.
Consider a simplified example.
Visible representation:
Quantity: 2
Unit price excluding tax: €100.00
Total excluding tax: €200.00
Illustrative XML representation:
<invoice>
<quantity>2</quantity>
<unitPrice>100.00</unitPrice>
<total>200.00</total>
</invoice>
This fragment is not a valid Factur-X XML document. It only illustrates the principle of structured data associated with an invoice.
Visualizing an Inconsistency
An interactive experience can demonstrate what happens when the two representations contain different values.
PDF: Total excluding tax = €200.00
XML: Total excluding tax = €250.00
Both values are individually readable, but they describe the same transaction differently.
Consistency between the representations is therefore a separate concern from their syntactic validity.
| Validation type | Objective |
|---|---|
| XML structure | Verify the data format |
| Business rules | Check relationships between fields |
| PDF / XML consistency | Compare shared information |
| Factur-X profile | Meet applicable requirements |
Actual Factur-X validation requires specifications and tools appropriate to the selected profile.
The interactive experience explains the underlying principle without attempting to replace a complete validation engine.
10. Sharing Presentation Without Standardizing Every Experience
The six experiences cover different subjects, but they can share common visual components.
An authentication stage and an invoice validation stage can be represented using a similar structure.
<section class="experience-step">
<h2>Validation</h2>
<p>
The system checks the received data.
</p>
<button type="button">
Next step
</button>
</section>
A shared CSS file can define reusable elements:
.experience-step {
padding: 1.5rem;
border: 1px solid #d1d5db;
border-radius: 8px;
}
.experience-step h2 {
margin-top: 0;
}
.experience-step button {
padding: 0.75rem 1rem;
cursor: pointer;
}
These examples illustrate the principle of shared presentation without reproducing the project's stylesheet.
A common CSS foundation maintains visual consistency across the experiences without imposing identical JavaScript logic on every subject.
One experience may follow a linear sequence, while another may offer multiple choices, comparisons, or different outcomes depending on user actions.
11. Designing a Bilingual Interface
The collection provides French and English versions.
The project structure separates pages by language while sharing the stylesheet.
assets/
└── interactive.css
fr/
└── securite.html
en/
└── security.html
This approach allows explanations and labels to be adapted without rebuilding the entire presentation layer.
For an interactive experience, translation involves more than headings.
It may also include:
- User instructions
- Stage descriptions
- Error messages
- Displayed results
- Action labels
Both language versions should preserve the same educational logic.
A translated stage should not introduce different technical behavior simply because its text has been adapted.
12. Educational Simulations vs. Real Systems
One distinction must remain clear throughout the design process: an interactive experience represents a mechanism but does not necessarily execute it under real operating conditions.
| Experience | Corresponding real system |
|---|---|
| Simulated API call | Client-server communication |
| Simulated login | Authentication and session handling |
| Illustrated cookie | Data storage and processing |
| Invoice exploration | Factur-X generation and validation |
| Automated task | Business rule execution |
A simulation can display an HTTP response without contacting a server.
It can represent an authentication check without handling real credentials.
It can demonstrate a profiling process without collecting the user's personal data.
This separation makes it possible to build lightweight experiences that are accessible directly in the browser.
However, it also introduces a requirement for precision: explanations must distinguish educational representations from the constraints of a real implementation.
Conclusion
Interactive experiences provide a complementary approach to explaining technical architectures and mechanisms.
By breaking an operation into stages, they make it possible to reveal the validations, exchanges, decisions, and errors that normally remain hidden behind an interface.
Native HTML, CSS, and JavaScript are sufficient to build this type of interactive sequence without introducing a frontend framework.
The main challenge is not necessarily the technology itself, but the ability to represent the underlying process accurately.
A well-designed interactive experience should not only demonstrate what happens when everything works. It should also help users understand why certain stages are necessary, which conditions can change the outcome, and where the limits of the simulation lie.
This distinction between visible actions and underlying mechanisms is what makes interactive experiences particularly useful for understanding technical systems.
Technical Documentation
The project architecture, file structure, technologies, and an overview of the six interactive experiences are documented in the GitHub repository.
The repository provides technical documentation rather than downloadable source code or production files.
View the technical documentation on GitHub
Top comments (0)