ReSECT Web Project

Clinical analytics website for the ReSECT registry (Registry of the Spanish Society of Thoracic Surgery), built with Quarto + R and deployed as a static site.

Project goal

This repository centralizes: - visualization of clinical activity and data quality, - participation and audit reports by users/centers, - clinical reports (e.g. lung cancer, postoperative course), - derived-project pages and news.

The site output is generated in _site/.

Technical stack

  • R (primary analysis environment)
  • Quarto Website (site structure and rendering)
  • tidyverse/ggplot2/plotly/DT (data transformation and visualization)
  • renv (dependency lockfile)
  • RStudio/Positron project (redcap.Rproj)

Repository structure

_quarto.yml            # Global site configuration (navbar, sidebar, format)
index.qmd              # Main landing page
blog.qmd               # News listing
styles.scss            # Global styles
R/                     # Reusable functions (audit, participation, reports, tools)
audit/                 # Audit reports
participation/         # Participation reports
reports/               # Clinical reports
projects/              # Center/topic-specific projects
tutorials/             # Dictionaries and functional documentation
data/                  # Serialized data (.RDS) used during rendering
_site/                 # Generated site (build artifact)

Functional architecture

1) Data layer

Report content is mainly fed from data/*.RDS: - rp.RDS: main lung resection process dataset, - usuarios.RDS, centros.RDS: catalogs and metadata, - procesos_*, oplog_*: activity and trace logs for participation/auditing.

2) Logic layer (R/)

Modular functions in R/: - rp_audit.R, rp_audit_user.R: audit metrics and visualizations, - rp_participation.R, rp_participation_user.R: participation by center/user, - reports_lung_cancer.R, report_postop.R: clinical reports, - procesos.R: utilities to analyze creation/edit logs, - tools.R: helper utilities (text normalization, pseudonymization, etc.).

3) Presentation layer (Quarto)

Each .qmd: - loads data from ./data/*.RDS, - uses source() to load functions from ./R/*.R, - composes tables/charts and publishes HTML into _site/.

Global navigation and sidebars are defined in _quarto.yml.

Local workflow (quick onboarding)

1. Clone and open the project

git clone <repo-url>
cd resect_redcap

Open redcap.Rproj in Positron or RStudio.

2. Restore dependencies

renv::restore()

Note: renv.lock is present, so restore should align package versions across the team.

3. Render the site

Full render:

quarto render

Render a specific page:

quarto render audit/department_audit_overall.qmd --to html

Local preview:

quarto preview

4. Minimum validation before commit

  • Confirm the modified page(s) render without errors.
  • Review changes in _site/ only if your workflow explicitly versions them.
  • Verify that no local absolute paths were introduced.

Project conventions

  • Preferred R coding style: tidyverse.
  • Avoid business logic inside .qmd: move it into functions in R/.
  • Keep file and function names descriptive by domain (audit_*, participation_*, etc.).
  • Reuse datasets in data/*.RDS; avoid duplicating structures.

How to add a new report

  1. Create a .qmd file in the relevant domain folder (audit/, reports/, etc.).
  2. Load the required data with readRDS().
  3. Reuse existing functions from R/ or create a new modular function.
  4. Add the link to menus/sidebars in _quarto.yml.
  5. Render that page locally and validate the result.

Data management and security

  • data/ is excluded in _quarto.yml as a publishing resource to avoid exposing raw source data in the site.
  • The .secret/ folder is ignored by Git (.gitignore): use it for local credentials and sensitive configuration.
  • Do not include tokens, keys, or private endpoints in versioned files.
  • If working with identifiable data, apply pseudonymization before exporting or sharing.

Key components for new developers

  • Site configuration: _quarto.yml
  • Global styles: styles.scss
  • Report entry points:
    • audit/*.qmd
    • participation/*.qmd
    • reports/*.qmd
  • Reusable logic: R/*.R
  • Reproducible environment: renv.lock

Common issues

  • Package errors during rendering: run renv::restore().
  • Functions not found: confirm source("./R/<file>.R") in the .qmd.
  • Missing data: verify presence and exact filename of data/*.RDS files.
  • Different output across machines: check R version and synchronization with renv.lock.

Contact and clinical context

  • ReSECT / SECT project
  • Registered study: NCT05600569

If you are joining the project, start by: 1) reading _quarto.yml, 2) reviewing R/rp_audit.R and R/rp_participation.R, 3) rendering index.qmd and one report in audit/ to verify the environment.