MASARYK UNIVERSITY FACULTY OF INFORMATICS Design and implementation of a new version of 2DProts database web pages Bachelor's Thesis MARIO MICULKA Brno, Spring 2026 MASARYK UNIVERSITY FACULTY OF INFORMATICS Design and implementation of a new version of 2DProts database web pages Bachelor's Thesis MARIO MICULKA Advisor: RNDr. Ivana Hutafova Vafekova, Ph.D. Department of Computer Systems and Communications Brno, Spring 2026 Declaration Hereby I declare that this paper is my original authorial work, which I have worked out on my own. A l l sources, references, and literature used or excerpted during elaboration of this work are properly cited and listed in complete reference to the due source. During the writing of this thesis, the following AI tools were used: - Claude (Anthropic) — used for brainstorming, generating simple code, reformulating thesis text and proofreading. - Grammarly AI — used for rewording and grammar checking. - Gemini (Google) — used for quick ideation. I have reviewed all AI generated content and take full responsibility for it. I declare I have used AI in accordance with the principles of academic integrity. Mario Miculka Advisor: RNDr. Ivana Hutařová Vařeková, Ph.D. iii Acknowledgements I would like to sincerely thank my supervisor, RNDr. Ivana Hutaf ova Vafekova, Ph.D., for her patience, feedback, and positivity throughout the development of this thesis. I also express my gratitude to my parents and those close to me for their support during my studies. iv Abstract The C A T H database classifies hundreds of thousands of protein domains into families based on structural similarity. The 2DProts project generates two-dimensional diagrams of secondary structure elements for these domains, providing a compact representation useful for comparing proteins within a family. The existing 2DProts web interface displays these diagrams as static images with no interactive capabili- ties. This thesis presents the design and implementation of a new webbased viewer for the 2DProts database. The application, built using React and TypeScript, allows researchers to interactively explore 2D diagrams through layer toggling, element-level tooltips and hiding, pan and zoom, and fullscreen mode. Performance-oriented rendering techniques, including direct D O M injection and CSS-driven visibility control, enable the viewer to handle large family diagrams containing thousands of SVG elements. The application currently serves tens of thousands of domains organized into hundreds of families, covering thousands of proteins. Keywords 2DProts, protein structure, CATH, web application, React, TypeScript, SVG, interactive visualization v Contents 1 Introduction 1 2 Theoretical Background 3 2.1 Protein structure 3 2.1.1 Amino acids 3 2.1.2 Levels of protein structure 4 2.2 Structural classification of proteins 6 2.2.1 C A T H 6 2.3 Ligands and tunnels 7 2.4 2D representations of protein structure 8 2.5 Existing solutions 9 3 Methods 11 3.1 SVG format 11 3.1.1 Packaging styles 11 3.1.2 Element ID conventions 12 3.2 P N G format 12 3.3 Technologies used 13 4 Design and Implementation 15 4.1 Specification 15 4.1.1 Functional requirements 15 4.1.2 Non-functional requirements 16 4.1.3 Inputs 17 4.1.4 Outputs 17 4.2 Architecture 17 4.2.1 User interface design 18 4.2.2 Routing 19 4.2.3 Dataflow 19 4.2.4 Project structure 20 4.3 Implementation 21 4.3.1 API data adaptation 21 4.3.2 Diagram rendering 22 4.3.3 Element interactivity 24 4.3.4 Visualizer component architecture 25 vi 5 Results and Deployment 26 5.1 Dataset 26 5.2 Application walkthrough 26 5.3 Deployment 29 5.4 Comparison with the previous version 30 6 Conclusion 32 A Attachments 33 Bibliography 34 vii List of Tables 4.1 Route structure of the application 19 5.1 Feature comparison between the previous and new 2DProts viewer 31 viii List of Figures 2.1 Generic structure of an amino acid. The central a-carbon (Ca ) is bonded to an amino group, a carboxylic group, a hydrogen atom, and a variable side chain (R) that differs between amino acid types 4 2.2 Abstraction of common secondary structure elements: (A) a-helix, (B) parallel /3-sheet, (C) antiparallel /3-sheet. 5 2.3 The sliding clamp protein (PDB entry 6GIS), visualized using Mol* [5]. The highlighted subunit represents the tertiary structure of a single polypeptide chain. The complete ring, formed by three such subunits, represents the quaternary structure 6 2.4 The four levels of the C A T H hierarchy, shown with the example identifier 1.10.10.1000. Each dot-separated number in a C A T H identifier corresponds to one level of the classification 7 2.5 Tunnels detected in PDB entry ltqn, computed and visualized using MOLEonline [9]. The protein structure is shown in dark green, with individual tunnels highlighted in distinct colors 8 2.6 Domain lorwBOl from family 2.140.10.30: 2D diagram as displayed by the application (left) and the corresponding 3D model from the C A T H database (right) 9 4.1 Directory layout of the application source code 21 4.2 D O M tree walk performed by getElementldAtPoint. . . . 24 5.1 The application landing page with search bar and database statistics 27 5.2 A family entity page showing the two-column layout with the interactive diagram in the main column and related entities in the side column 28 5.3 Family 1.10.630.10 with different layer combinations: (A) SSEs only, (B) SSEs with ligands, (C) Tunnels only. 29 5.5 Search results for a sample query, displayed in the tabbed grid view. 29 ix 5.4 View of protein ldm8 from family 1.10.630.10, with tunnels larger than 50 hidden 30 5.6 Comparison of the previous 2DProts viewer (left) and the new application (right) displaying the same entity. . . 31 x 1 Introduction The number of experimentally determined protein structures has grown rapidly over the past decades, and with them the need to organize and compare these structures systematically. The C A T H database [1] classifies protein domains into a hierarchy of families based on their functional, evolutional and structural similarity —a classification that is performed semi-automatically and stored as an integral part of the database. Understanding how proteins within a family relate to each other — which structural features they share and how they differ — is an important question in structural bioinformat- ics. One approach to navigating this complexity is through two dimensional representations of protein structure. By projecting key structures such as secondary structure elements, ligands, and tunnels onto a plane, 2D diagrams offer a compact view that is well suited for comparison across members of a protein family. The 2DProts project [2] generates such diagrams for protein domains classified in the C A T H database. The 2DProts project has an existing web interface for browsing these diagrams, but it presents them as static images with no interactive capabilities and does not display information about tunnels or ligands. As the volume of structural data continues to grow, these limitations become increasingly restrictive. The goal of this thesis is to design and implement a modern, interactive web-based viewer for the 2DProts database. The viewer should allow researchers to browse families, family clusters, proteins, and domains, interactively explore their 2D diagrams through layer control and element-level inspection, and navigate between related structures. The application should handle diagrams of varying complexity, including large family diagrams with thousands of SVG elements. The thesis is organized as follows. Chapter 2 introduces the biochemical and bioinformatic concepts needed to understand the diagrams. Chapter 3 describes the data formats produced by the 2DProts pipeline and the technologies used in the implementation. Chapter 4 covers the specification, design, architecture, and implementation of the application. Chapter 5 presents the deployed application, a walk- 1 i . INTRODUCTION through of its features, and a comparison with the previous viewer. Chapter 6 concludes the thesis and discusses future work. 2 2 Theoretical Background This chapter introduces the biochemical and bioinformatic concepts that are necessary for understanding the diagrams visualized by the application. The level of detail is limited to what is directly relevant to the thesis; for more comprehensive information about the subjects, the reader is referred to standard textbooks [3,4]. 2.1 Protein structure Proteins [3,4] are biomolecules responsible for a wide range of biological functions, such as accelerating chemical reactions, transmitting signals between cells, and transporting molecules. They are found in all living organisms and are among the most studied subjects in bioinformatics. A protein is built from one or more chains of smaller building blocks called amino acids. 2.1.1 Amino acids Amino acids [3] are small organic molecules that serve as the building blocks of proteins. A l l known proteins are assembled from a set of 20 standard amino acids (with three rare additions: selenocysteine, pyrrolysine, and N-formylmethionine). Each amino acid consists of a central a-carbon atom (Ca ) bonded to four groups: an amino group (—NH2), a carboxylic group (—COOH), a hydrogen atom, and a variable side chain that determines the properties of the amino acid. Amino acids are commonly referred to by three-letter or one-letter abbreviations (e.g. Ala or A for alanine). Amino acids are linked together by peptide bonds [3], formed between the carboxylic group of one amino acid and the amino group of another, releasing a water molecule. The resulting chain is called a polypeptide. Within a polypeptide, the individual amino acids are referred to as residues. The chain has directionality: the end with a free amino group is called the N-terminus, and the end with a free carboxyl group is the C-terminus. 3 2. THEORETICAL BACKGROUND H amino group carboxylic group H2 N COOH side chain (variable) Figure 2.1: Generic structure of an amino acid. The central a-carbon (Ca ) is bonded to an amino group, a carboxylic group, a hydrogen atom, and a variable side chain (R) that differs between amino acid types. 2.1.2 Levels of protein structure Protein structure is described at four levels of abstraction [3,4]. Primary structure. The simplest description of a protein is its primary structure: the ordered list of residues that make up its chains. It is conventionally written using one-letter codes for each amino acid, starting from the N-terminus and ending at the C-terminus. Secondary structure. Secondary structure describes how the protein chain is arranged in space. The geometry is determined by torsion angles between chain atoms and is stabilized by hydrogen bonds between residues. A part of the protein chain that follows a regular geometric pattern is called a secondary structure element (SSE). The two most common types of SSEs are a-helices and /3-sheets (Figure 2.2). • A n A;-helix [3] is the most common type of SSE. The backbone coils into a right-handed spiral with approximately 3.6 residues per turn. The structure is held together by hydrogen bonds, each connecting a residue to the one four positions ahead in the chain. • A /3-sheet [3] consists of multiple /3-strands — short, nearly fully extended segments of the backbone — running side by side. 4 2. THEORETICAL BACKGROUND Hydrogen bonds form between neighboring strands rather than within a single strand. Depending on whether adjacent strands run in the same or opposite directions, the sheet is classified as parallel or antiparallel. Figure 2.2: Abstraction of common secondary structure elements: (A) a-helix, (B) parallel /3-sheet, (C) antiparallel /3-sheet. Regions of the chain that connect SSEs but do not follow a regular pattern are called turns and loops. These regions are generally more flexible and variable across related proteins. Secondary structure is central to this thesis: the 2D diagrams produced by the 2DProts pipeline represent the relative positions and distances between SSEs within a protein domain. Tertiary structure. Tertiary structure (Figure 2.3) describes how all the atoms in a protein chain are arranged in three-dimensional space [3]. At this level, SSEs do not exist in isolation — they pack together and interact through various forces, including disulfide bonds and van der Waals interactions. The resulting three-dimensional shape can be broken down into hierarchical units: motifs (a few SSEs that interact closely), folds (combinations of motifs), and domains (larger, structurally independent regions that can fold on their own) [4]. Domains are the units classified by databases such as C A T H (Section 2.2). (A) (B) (C) 5 2. THEORETICAL BACKGROUND Quaternary structure. Some proteins consist of multiple polypeptide chains, called subunits. Quaternary structure describes how these subunits are arranged relative to one another [3]. Not all proteins exhibit quaternary structure. Figure 2.3 shows an example of both tertiary and quaternary structure in a single protein. Figure 2.3: The sliding clamp protein (PDB entry 6GIS), visualized using Mol* [5]. The highlighted subunit represents the tertiary structure of a single polypeptide chain. The complete ring, formed by three such subunits, represents the quaternary structure. 2.2 Structural classification of proteins Many proteins share structural features with other proteins, and the degree of resemblance varies widely. Proteins that share biological function and localization within organisms are often similar in structure — structural similarity is frequently a consequence of shared evolutionary origin. Over time, databases have been developed to organize proteins into groups based on these similarities. Such a group is commonly called a protein family [4]. 2.2.1 CATH C A T H [1] is a protein structure classification database that organizes domains into a four-level hierarchy. At the top level, Class separates domains by the predominant type of SSE they contain (e.g. mostly 6 2. THEORETICAL BACKGROUND helices, mostly sheets, or a mix). The second level, Architecture, captures the overall shape formed by the SSEs. Topology, as the third level, further distinguishes domains by the order in which SSEs are connected along the chain. Finally, the Homologous superfamily level groups domains that are thought to share a common ancestor. C A T H identifiers use a dotted numeric notation reflecting this hierarchy, as illustrated in Figure 2.4. Class 10 10 1000 Architecture Topology Homologous superfamily Mainly Alpha Orthogonal Bundle Figure 2.4: The four levels of the C A T H hierarchy, shown with the example identifier 1.10.10.1000. Each dot-separated number in a C A T H identifier corresponds to one level of the classification. The 2DProts database organizes its data around the CATH classification. Families and clusters correspond directly to levels within the CATH hierarchy, while proteins and domains are biochemical entities sourced from the Protein Data Bank [6]. Other classification systems exist, notably SCOP [7] and Pfam [8], but they are not used in this thesis. 2.3 Ligands and tunnels Besides SSEs, protein structures contain other features that appear in the diagrams produced by 2DProts. 7 2. THEORETICAL BACKGROUND Ligands. A ligand is a molecule that binds to a specific site on a protein [3]. Ligands play important roles in protein function — they can act as substrates in enzymatic reactions, as signaling molecules, or as structural cofactors. Being able to examine their spatial relationship to the secondary structure elements is often vital. Tunnels. Proteins are not solid objects — their interiors contain empty spaces that can serve as pathways for small molecules. A tunnel (also called a channel) is a void that leads from the surface of the protein into its interior, typically toward a ligand binding site [9]. A passage that traverses the entire protein structure is called a path. These features can be found in all types of proteins. A n example of detected tunnels is shown in Figure 2.5. Detecting and analyzing these pathways is important for understanding protein function, particularly in enzymology and drug design [9]. Figure 2.5: Tunnels detected in PDB entry ltqn, computed and visualized using MOLEonline [9]. The protein structure is shown in dark green, with individual tunnels highlighted in distinct colors. 2.4 2D representations of protein structure While protein structures exist in three dimensions, two-dimensional representations offer a useful way to compare structural features across proteins in the same family. A 2D diagram of a protein domain projects 8 2. THEORETICAL BACKGROUND key structural features onto a plane, emphasizing their relative position and sequential relationships rather than their exact spatial coordinates [2], making it easier to compare which structures are shared across members and which differ. Figure 2.6 shows a 2D diagram alongside the corresponding 3D model of the same domain, illustrating how the three-dimensional structure is projected onto a plane. The 2DProts pipeline [2] generates such diagrams for protein domains cataloged in the C A T H database. The output formats produced by this pipeline are described in Section 3.1. Figure 2.6: Domain lorwBOl from family 2.140.10.30: 2D diagram as displayed by the application (left) and the corresponding 3D model from the C A T H database (right). 2.5 Existing solutions The 2DProts project has an existing web interface that serves as the predecessor to the application developed in this thesis. The original viewer displays precomputed 2D diagram images for families, clusters, proteins, and domains and allows navigation between families, clusters, proteins, and domains. However, the original interface has several limitations. The diagrams are presented as static images with no interactive capabilities — the user cannot toggle individual layers, inspect, nor hide, specific structural elements. There are no tooltips identifying elements on hover; the user must visually interpret the diagram without assistance 9 2. THEORETICAL BACKGROUND from the application. Pan and zoom functionality is absent, which makes it difficult to examine fine details in larger, more crowded dia- grams. These limitations motivated the development of a new viewer that presents the same underlying data through a modern, interactive interface. The requirements for this new viewer are defined in Section 4.1. 10 3 Methods The 2DProts pipeline [2] generates 2D SSE diagrams for proteins and their domains from the Protein Data Bank [6], and for protein families and their clusters from the C A T H database [1]. The generation algorithm itself is outside the scope of this thesis. This chapter describes the output formats that the pipeline produces and that the application consumes, as well as the technologies used to build the viewer. 3.1 SVG format The 2DProts pipeline produces SVG [10] diagrams in two distinct packaging styles, depending on the entity type. Understanding these formats is essential context for the rendering approach described in Section 4.3.2. 3.1.1 Packaging styles Single-file packaging. For domain and protein entities, the pipeline produces a single SVG file that contains all diagram layers: sses (secondary structure elements), l i n k s (connections between SSEs), ligands, and tunnel. Each layer is represented as a (group) element identified by a CSS class — for example, for secondary structure elements. Because all layers reside in one file, visibility can be controlled through CSS class selectors without manipulating separate resources. Multi-file packaging. For family and cluster entities, the pipeline produces a separate SVG file for each layer: channels, ligands, sses, sses2 (a second set of SSE annotations), and template. Each file contains an independent SVG document with its own coordinate system, though all files for a given entity share the same viewBox dimensions, allowing them to be overlaid. 11 3. METHODS 3.1.2 Element ID conventions Individual elements within the SVG diagrams carry i d attributes that encode the element type and structural properties in a compact format. These IDs are not arbitrary — they follow conventions defined by the 2DProts pipeline and are relied upon by the viewer for interactive features such as tooltips and element hiding (Section 4.3.3). Three ID patterns are used: 1. Secondary structure elements. The ID consists of a single uppercase letter indicating the SSE type, followed by three underscoreseparated integers: an index, a start residue number, and an end residue number. For example, H0 19 42 denotes the first helix spanning residues 19 to 42. The type codes follow standard biochemical convention: H for helix and E for strand (extended). 2. Tunnels and channels. Tunnel and channel elements use a numeric identifier that serves as the element's name. The identifier may be an integer or a decimal number (e.g. 12 or 50.231), depending on which detection tool in the pipeline produced it. 3. Ligand compounds. Ligands use an ID in the format {hetcode}_ {posl}_{pos2}_{name}, where the compound name uses hash characters (#) in place of spaces. The two middle positions are currently reserved for future use with nucleic acid structures. For example, HEM_x_x_PR0T0P0RPHYRIN#IX#FE represents a protoporphyrin IX compound containing iron. 3.2 PNG format For family and cluster entities, the pipeline also produces P N G versions of each diagram layer. The files use the same layer names as the multi-file SVG packaging. Each PNG is a standalone raster image with identical dimensions across layers, designed to be stacked on top of one another to form the complete diagram. Domain and protein entities do not have P N G representations; their diagrams are available only in SVG format. 12 3. METHODS 3.3 Technologies used This section describes the main technologies used in the implementation and the reasoning behind their selection. The selection of technologies favors widely adopted, industry-standard tools — since the 2DProts project is under active development, using popular tools lowers the barrier for future contributors and ensures strong community support and documentation. TypeScript. TypeScript [11] extends JavaScript with static type checking. It was chosen because the application works with multiple entity types that differ in data shape and behavior. Compile-time type checking prevents a broad class of errors that would otherwise surface only at runtime. React. React [12] is a library for building user interfaces through composable components. It also allows for direct D O M manipulation, which is essential for the optimization strategy chosen for rendering large SVG diagrams efficiently (Section 4.3.2). Frameworks with stronger abstraction layers over the D O M would make low-level rendering strategies more difficult to implement. Vite. Vite [13] serves as the build tool and development server. It provides fast hot module replacement during development and a configurable proxy server, which allows the frontend to be developed independently from the 2DProts backend. TanStack Router. TanStack Router [14] provides file-based routing with type-safe route parameters and built-in data loading. Type safety in this context means that route parameters, navigation targets, and loader return types are all checked at compile time — a mistyped route path or a missing parameter is caught before the application runs, rather than manifesting as a runtime error. Routes can also declare what data they require, ensuring it is available before the page component renders. 13 3. METHODS TanStack Query. TanStack Query [ 15] manages all data fetching and caching. It provides automatic cache deduplication, meaning multiple requests for the same resource result in a single network call. Cached data is reused on subsequent navigations, and configurable stale times control when data should be refetched. It also provides declarative loading and error states, freeing components from managing request lifecycle manually — components simply declare what data they need, and the library handles fetching, caching and state transitions. Zod. Zod [16] is a schema validation library. It validates data at runtime and can infer TypeScript types directly from schemas, providing a single source of truth for data shapes across both validation logic and application code. react-zoom-pan-pinch. The react-zoom-pan-pinch library [17] provides pan and zoom functionality via CSS transforms on a wrapper element. Because it operates on the container rather than the content, the wrapped elements are not re-rendered during interaction, which is important for performance with large SVG documents. Tailwind CSS. Tailwind CSS [18] is a utility-first CSS framework. It allows styles to be defined directly in component markup, keeping styling co-located with components it affects and avoiding the overhead of managing separate stylesheets. 14 4 Design and Implementation 4.1 Specification The goal of this thesis is to design and implement an interactive webbased viewer for 2D diagrams of protein secondary structures stored in the 2DProts database. The viewer consumes data served by a preexisting 2DProts server and interactively presents it through a modern, publicly accessible application. This section defines the functional requirements placed on the application, followed by a description of its inputs and outputs. 4.1.1 Functional requirements The application shall support browsing and interactive visualization of four entity types: families and clusters (defined by the C A T H classification) and proteins and domains (sourced from the Protein Data Bank). Each entity type has a dedicated detail page displaying its 2D architecture diagram with related information. The specific requirements are as follows. 2D diagram visualization. Each entity page displays an interactive 2D architecture diagram in the main content area. For family and cluster diagrams, users can switch between two available image formats P N G and SVG. In the case of protein and domain diagrams, only the SVG format is presented. Layer control. The diagrams are composed of multiple layers (e.g., secondary structure elements, ligands, channels). The user can independently toggle the visibility of each layer to focus on specific structural features. Element-level interaction. In SVG mode, individual diagram elements are interactive. Hovering over an element displays a tooltip with a human-readable label (e.g. Helix 2 - residues 19-42). A dedicated hide mode allows the user to click on elements to remove 15 4. DESIGN A N D IMPLEMENTATION them from the diagram, with the ability to restore hidden elements individually or all at once. Pan, zoom and fullscreen. The diagram supports panning and zooming to allow inspection of finer details in crowded diagrams. A fullscreen mode expands the viewer to cover the entire page. Download. The user can download the currently displayed diagram in its actual format. Search. The application supports basic search functionality, allowing querying across families, proteins, and domains. Results are displayed in a tabbed interface with category entry counts. Navigation between entities. Entity pages provide sequential navigation to the previous and next entity of the same type. Side panels display lists of related entities (e.g. a family page lists its domains and clusters), which serve as navigation links. 3D model preview. Each entity page includes a static 3D model image sourced from the CATH database, linking to the corresponding C A T H superfamily page for further exploration. 4.1.2 Non-functional requirements The viewer must handle diagrams that are often very large and vary greatly in complexity. Family diagrams in particular can contain thousands of SVG elements, so the rendering approach must be chosen with performance in mind. Since the application is publicly accessible and intended for use by researchers, it should function on any reasonable computer setup. Responsive behavior on smaller screens is desirable, but not a primary concern, as the target audience predominantly works on desktop dis- plays. The codebase should remain maintainable and extensible, as the 2DProts project is under active development and future visualization needs or database changes may warrant additional changes. 16 4. DESIGN A N D IMPLEMENTATION 4.1.3 Inputs The application consumes two categories of data from the 2DProts server: 1. Structured data provided by a REST API. Each entity type has a dedicated endpoint (e.g. / a p i / f amily/{id}) that returns a JSON object containing the entity's metadata, related entities, navigation links and version information. A search endpoint (/api/search/{query}) returns matching families, proteins and domains. A l l API responses are validated against Zod schemas at the application boundary. 2. Image files served as static assets. These include SVG and P N G diagram files that are distributed in either single or multiple layers. 4.1.4 Outputs The viewer is a client-side application; its primary output is the rendered user interface. Additionally, the download function offers an SVG or P N G file that the user can store locally. The viewer does not modify any data on the server. 4.2 Architecture This section describes the architecture of the application: design choices, its routing model, the flow of data from the server to the rendered interface, and the organization of the source code. No separate backend was developed as a part of this thesis; the only server-side addition is a set of API endpoints integrated into the existing 2DProts server to provide entity data in the format expected by the application. During development, the Vite development server proxies requests matching / a p i / , / f i l e s / , and / s t a t i c / to the 2DProts staging server, allowing the frontend to be developed independently without cross-origin issues. In production, the built application is deployed separately and communicates with the 2DProts server directly. 17 4. DESIGN A N D IMPLEMENTATION 4.2.1 User interface design The U I design was shaped by the needs of the target audience — researchers navigating complex structural data. This subsection describes key layout and interaction decisions. The design choices made are supported by Nielsen's usability heuristics [19], a widely adopted set of principles for interaction design, and Nielsen's Progressive Disclosure [20]. Two-column layout with a fixed diagram. Each entity page is divided into two columns. The main column contains the interactive diagram and remains stationary, while the side column is independently scrollable and holds contextual information. This allows researchers to scroll through related data while keeping the diagram visible, enabling direct comparison without navigating away. Dual search entry points. The application provides two search inputs. A compact search bar in the navigation bar is present on every page, giving experienced users a consistent, predictable location they can rely on through repeated use (Consistency and standards [19]). The landing page additionally features a prominent, centrally placed search bar that signals the primary purpose of the application to firsttime visitors (Recognition rather than recall [19]). Minimal interface. The interface limits each page to information directly relevant to the current entity. Since researchers work with complex structural data, reducing visual noise helps them focus on the diagram and its contextual data without distraction (Aesthetic and minimalist design [19]). Progressive disclosure of controls. Several interface elements appear only when contextually relevant. For example, the hidden-elements bar is absent until the user hides at least one element, and the format switcher is absent when only one format is available. This keeps the default state of the interface uncluttered and introduces complexity only when the user's actions require it [20]. 18 4. DESIGN A N D IMPLEMENTATION Self-explanatory controls. Interactive controls make use of recognizable icons, text labels and tooltips. The goal is that no control requires extensive prior explanation to understand and operate the application effectively (Recognition rather than recall [19]). Continuity with the previous version. The layout and navigation patterns were designed with awareness of the existing 2DProts website, so that researchers accustomed to the previous version do not need to relearn fundamental interaction patterns (Consistency and standards [19]). 4.2.2 Routing The application uses file-based routing, where each file in the routes/ directory corresponds to a URL path. The route structure reflects the entity types present in the 2DProts database: Table 4.1: Route structure of the application. Route Page Content / Dashboard Landing page with search /search/{query} Search Results across entity types /family/{id} Family Diagram, 3D image, domains, clusters /cluster/{id} Cluster Diagram, 3D image, parent family /domain/{id} Domain Diagram, 3D image, parent family, protein /protein/{id} Protein Diagram, 3D image, domains Each entity route defines a loader function that ensures the required data is available — either from the client-side cache or via a network request — before the page component mounts. 4.2.3 Dataflow Data flows through the application in three stages: 1. Fetching. When a route is entered, its loader asks the cache for the required data. O n a cache miss, the cache delegates to the API service module (api. ts), which issues a fetch request to 19 4. DESIGN A N D IMPLEMENTATION the appropriate endpoint. Each entity type has a dedicated function (e.g. getFamilyData). On a cache hit, no network request is made. 2. Validation. The raw JSON response is immediately parsed and validated against a Zod schema (Section 3.3). If the response does not match the expected structure, an error is thrown before any component receives the data. This provides a runtime guarantee that the data conforms to the TypeScript types used throughout the application. 3. Caching and rendering. Validated data is stored in the clientside cache. Components access it through query hooks, which return typed objects directly. Subsequent navigation to the same entity reuses the cached data without repeating the first two stages. Diagram assets (SVG and P N G files) follow a parallel path: they are fetched by the visualizer component and cached independently with an infinite stale time, since diagram files do not change within a data version. 4.2.4 Project structure The directory layout, shown in Figure 4.1, separates concerns into clearly defined modules. The top-level split between s r c / l i b / and src/f rontend/ is intentional. Zod validation schemas are decoupled from the frontend and can be reused by a potential future backend without introducing a dependency on frontend code. Within src/f rontend/, the organization follows common conventions for React applications. The routes/ directory is used exclusively for file-based routing; each file defines a route, its loader and corresponding page component. The components/ directory contains reusable UI components at three levels of abstraction: u i / holds unmodified third-party components, ui_custom/ holds small reusable components, and the top level holds larger, application-specific com- ponents. 20 4. DESIGN A N D IMPLEMENTATION src/ +— l i b / I +— schemas.ts +— frontend/ +— main.tsx +— routes/ +— components/ I +— layouts/ I +— u i / I +— ui_custom/ +— hooks/ +— services/ +— types/ +— u t i l s / +— assets/ Figure 4.1: Directory layout of the application source code. Application logic that is not tied to a single component resides in hooks/ (stateful React hooks), services/ (pure modules for API communication, U R L construction, and data transformation), and types/ (shared TypeScript type definitions). The u t i l s / directory contains general-purpose helper functions with no dependency on the application domain. 4.3 Implementation This section describes the implementation of the most technically demanding parts of the application. Routing, configuration, search and page layouts are not discussed here, as they follow conventional patterns. The focus is on solutions specific to the problem domain. 4.3.1 API data adaptation The 2DProts server returns all entities — families, clusters, proteins and domains — in the same JSON shape: an object with an i d and a name. The server provides no type discriminator. However, frontend 21 4. DESIGN A N D IMPLEMENTATION must branch on entity type frequently: layer definitions, U R L construction, and rendering strategy all differ between entity types (as described in Section 3.1). To resolve this, each entity schema is created through a shared factory function createTypedSchema that accepts a type name as a parameter. The resulting Zod schema validates the incoming { i d , name} object and then applies a transform step that injects a type field with the given literal value. Since the transform runs at the API boundary (Section 4.2.3), every object that enters the application already carries its type, and all downstream code can rely on discriminated unions [21] without additional runtime checks. 4.3.2 Diagram rendering For PNG diagrams, rendering is straightforward: each layer is an independent image file, and the layers are stacked as absolutely positioned elements. Layer visibility is controlled by toggling CSS display on individual images. SVG diagrams, by contrast, present several challenges that required purpose-built solutions. The remainder of this subsection focuses on SVG rendering. Two packaging styles. The two SVG packaging styles described in Section 3.1 require different fetching strategies but must result in the same renderable output. A dedicated hook (useSvgContent) normalizes both into a single unit — a viewBox string and an H T M L string of inner SVG content. For single-file diagrams (domains and proteins), the hook detects that all layer URLs are identical and fetches only once, returning the parsed content as-is. For multi-file diagrams (families and clusters), each file is fetched in parallel, parsed, and the resulting content is wrapped in a element before concatenation. The consuming component receives the same interface regardless of the source packaging. This normalization has an important consequence: since both packaging styles produce the same class-named structure, layer visibility can be controlled through a single mechanism regardless of entity type, as described in the CSS-driven visibility paragraph. 22 4. DESIGN A N D IMPLEMENTATION D O M injection. A typical React approach would parse the SVG markup into a tree of React elements. For smaller protein diagrams with a few hundred elements, this would be acceptable. However, family diagrams can often contain thousands of elements. Building and reconciling a React element tree of that size on every render would introduce substantial lag, as React's diffing algorithm must traverse the entire tree to determine what changed [22]. Instead, each fetched SVG string is passed through a lightweight parser that uses the browser's native DOMParser to extract the viewBox attribute and the inner content of the root element, discarding the outer element itself. The resulting markup is then injected directly into the D O M using React's dangerouslySetlnnerHTML [23]. This bypasses the virtual D O M entirely: the browser's native H T M L parser handles the markup in a single pass, and React never tracks individual SVG elements. The result is that the rendering cost scales with the browser's native parsing speed rather than with React's reconciliation overhead. However, for the largest family diagrams, even native D O M injection produces severe delays, and alternative approaches (such as canvas-based rendering) may be worth exploring in future work. CSS-driven visibility. Both layer toggling and element-level hiding are implemented through a single injected