How leafac/kill-the-newsletter works
Project type and purpose
• From the README (“Convert email newsletters into Atom feeds”) and the file layout (Node/TypeScript files, a static folder, configs), this is a single-service web application (full-stack but light on “frontend”) whose core function is:
• Accept or fetch newsletter content (HTML or email)
• Parse and transform it into a valid Atom XML feed
• Serve that feed (and a small static site/documentation) over HTTP
• It ships as a Node.js service with TypeScript (using .mts modules) and delivers both dynamic API endpoints and static assets.
File structure
• Top-level
• package.json, tsconfig.json → Node/TypeScript runtime and compiler configuration
• .github/workflows/main.yml → CI pipeline definition
• Directories
• configuration/ → environment-specific settings (development, example, production, systemd service)
• source/ → core application code (index.mts) and tests (index.test.mts)
• static/ → static assets (HTML/CSS/JS for the site or docs)
• No separate “frontend” folder: the “frontend” is lightweight static files; all dynamic logic lives in one service.
README for additional insights
• The service is configured per-environment via the configuration folder
• CI (GitHub Actions) runs tests and deploys to a server (likely systemd, given the .service file)
Main components and their interactions
a. Client / Browser
– Requests Atom feeds or visits the static site
b. Static-asset host
– Serves the contents of static/ (HTML, CSS, JS)
c. Node.js Application (in source/index.mts)
– HTTP server (e.g., Express or built-in)
– Routing:
• /feed/:newsletterId → invokes parser
• /docs etc. → serves static/ files
d. Configuration Loader
– Reads from configuration/{environment}.mjs
e. Parser Module
– Core logic that takes raw newsletter HTML/email and outputs Atom XML
f. Testing Suite
– Unit tests in source/index.test.mts, run via CI
g. CI/CD Pipeline
– GitHub Actions (.github/workflows/main.yml) runs tests, builds, and (via the .service file) deploys to production
h. Package Manager / Dependency Graph
– package.json specifies libraries (e.g., HTML parsers, HTTP frameworks)
Architectural patterns and design principles
• Modular separation:
• Configuration layer (environment files)
• Application layer (server + parser)
• Presentation layer (static assets)
• Single-responsibility: parser logic isolated from HTTP routing
• Environment-driven configuration for flexibility across dev/stage/prod
• CI/CD ensures automated testing and deployment