Stay Sidekick Project Structure and Codebase Layout

Stay Sidekick is organized as a monorepo with four main directories — web/, frontend/, backend/, and nginx/ — plus shared tooling at the root. Understanding the layout helps contributors navigate the codebase, locate the right module for a change, and understand how the Node subprojects relate to one another through the root pnpm orchestration scripts.

Project directory tree

The full repository structure, as documented in the README, is as follows:

tfg-alberti/
├── web/                    # Static site — 11ty + Nunjucks
│   ├── src/
│   │   ├── _includes/      # Nunjucks layouts and partials
│   │   ├── _data/          # Global site data
│   │   ├── assets/styles/  # SCSS entry (compiles from frontend/src/styles/)
│   │   ├── producto/       # Product pages
│   │   ├── legal/          # Legal pages
│   │   └── empresa/        # Company pages
│   └── eleventy.config.js
│
├── frontend/               # Angular SPA
│   └── src/
│       ├── app/
│       │   └── components/ # Standalone components (header, footer…)
│       └── styles/         # SCSS shared with web/ (ITCSS)
│           ├── settings/   # Variables: typography, colors, breakpoints
│           ├── tools/      # Reusable mixins
│           ├── generic/    # CSS resets
│           ├── elements/   # Base HTML element styles
│           ├── layout/     # Grid, flex, container
│           ├── components/ # BEM atoms and organisms
│           ├── utilities/  # Utility classes
│           └── animations/ # Keyframes and transitions
│
├── backend/                # Flask REST API
│   └── app/
│       ├── contact/        # Public contact form module
│       ├── security/       # CSRF, honeypot, JWT
│       └── services/       # Mailgun (HTTP API), Discord, Turnstile
│
├── docs/                   # Project documentation
├── package.json            # Development orchestrator (concurrently)
├── dev.sh                  # Quick start — Linux / macOS
└── dev.bat                 # Quick start — Windows

Backend structure

The Flask API lives under backend/app/ and is organized around Blueprint modules. Each operational feature of the platform is an isolated Blueprint, and shared infrastructure lives in dedicated modules consumed by all of them.

Feature Blueprints

Each operational tool is a self-contained Blueprint with its own routes.py, service.py, repository.py, schemas.py, and model.py:

h_maestro_apartamentos — apartment master catalogue, PMS sync, XLSX import
h_mapa_de_calor — operational heatmap, date-range check-in/out visualization
h_notificaciones_tardias — late check-in detection and message templates
h_sincronizador_contactos — Google Contacts OAuth sync and CSV export
h_vault_comunicaciones — communication templates with optional AI assistance

Shared Modules

Cross-cutting modules used by all Blueprints:

auth — JWT HS256 authentication, BCrypt password hashing
empresas — multi-tenant company management and onboarding
usuarios — user management, roles, and password reset
perfil — per-company profile configuration and integrations
contact — public contact form endpoint
solicitud — company sign-up request flow
security — CSRF double-submit cookie, JWT guard, honeypot, IP whitelist
common — Fernet crypto (crypto.py), AI service, XLSX reservation parsing, sanitizers

Frontend structure

The Angular 21 SPA lives under frontend/src/app/. Components are built as standalone Angular components following an atomic design hierarchy — atoms, molecules, organisms — and are organized under frontend/src/app/components/. The shared SCSS design system lives at frontend/src/styles/ and follows the ITCSS (Inverted Triangle CSS) architecture with BEM naming conventions:

ITCSS Layer	Directory	Contents
Settings	`settings/`	Global variables — typography, colour tokens, breakpoints
Tools	`tools/`	Reusable Sass mixins and functions
Generic	`generic/`	CSS resets and box-model normalization
Elements	`elements/`	Base styles for bare HTML elements
Layout	`layout/`	Grid system, flex helpers, container
Components	`components/`	BEM-named UI atoms and organisms
Utilities	`utilities/`	Single-purpose utility classes
Animations	`animations/`	`@keyframes` and transition definitions

SCSS styles are shared between web/ and frontend/ — the public 11ty site compiles its stylesheets directly from frontend/src/styles/. Any change to a style in that directory will affect both the Angular SPA and the public static site simultaneously.

Public site

The public-facing marketing and legal content is a static site built with 11ty + Nunjucks, located in web/src/. It is entirely separate from the Angular SPA and does not require a running backend to build or serve.

_includes/

Nunjucks layouts and reusable partials shared across all public pages.

_data/

Global data files (JSON/JS) injected into Nunjucks templates at build time.

producto/, legal/, empresa/

Content directories for product feature pages, legal notices (GDPR, LSSI-CE), and company information pages.

The web/src/assets/styles/ directory contains only the SCSS entry point — the actual source layers are resolved from frontend/src/styles/ at compile time by 11ty’s asset pipeline.

Root pnpm orchestration

The root package.json orchestrates all Node subprojects from a single location using pnpm -C <dir> to delegate commands into each sub-directory. There is no workspaces field — the root package simply wires up convenience scripts. The concurrently package is the only root-level dev dependency; it is used to run 11ty and Angular in parallel during development.

{
  "name": "stay-sidekick",
  "packageManager": "pnpm@10.4.1",
  "scripts": {
    "dev": "concurrently --kill-others-on-fail --names \"11ty,angular\" --prefix-colors \"cyan,magenta\" \"pnpm run dev:web\" \"pnpm run dev:app\"",
    "dev:web": "pnpm -C web start",
    "dev:app": "pnpm -C frontend start",
    "install:all": "pnpm -C frontend install && pnpm -C web install"
  },
  "devDependencies": {
    "concurrently": "^9.0.0"
  }
}

Running pnpm run dev from the repo root is the standard way to start local development. Both services stream their output to the same terminal, colour-coded by prefix (cyan for 11ty, magenta for Angular). If either process exits with a non-zero code, --kill-others-on-fail terminates the other automatically.

Development scripts

The following pnpm scripts are available from the repository root:

Script	What it does	Port
`pnpm run dev`	Start all Node services (11ty + Angular) concurrently	8080, 4200
`pnpm run dev:web`	Start only the 11ty static site	8080
`pnpm run dev:app`	Start only the Angular SPA	4200
`pnpm run install:all`	Install all Node dependencies across `frontend/` and `web/`	—

The Flask backend is not managed through the root pnpm scripts. Start it separately with:

cd backend
python run.py

Enable pnpm via Corepack

corepack enable

This activates pnpm 10 automatically from the packageManager field in package.json without a separate install.

Install all Node dependencies

pnpm install
pnpm run install:all

The first command installs root devDependencies (concurrently). The second installs dependencies inside both frontend/ and web/.

Start all Node services

pnpm run dev

Opens the 11ty dev server at http://localhost:8080 and the Angular dev server at http://localhost:4200 in the same terminal session.

Get Started

Core Features

Administration

Deployment

Development

Stay Sidekick Project Structure and Codebase Layout

Project directory tree

Backend structure

Feature Blueprints

Shared Modules

Frontend structure

Public site

_includes/

_data/

producto/, legal/, empresa/

Root pnpm orchestration

Development scripts

Build docs developers (and LLMs) love

Get Started

Core Features

Administration

Deployment

Development

Documentation Index

​Project directory tree

​Backend structure

Feature Blueprints

Shared Modules

​Frontend structure

​Public site

_includes/

_data/

producto/, legal/, empresa/

​Root pnpm orchestration

​Development scripts

Build docs developers (and LLMs) love

Project directory tree

Backend structure

Frontend structure

Public site

Root pnpm orchestration

Development scripts