Macaroni KID
A national network of local newsletters and event guides for parents and families — and the engineering systems that publish, search, and deliver that content.
macaroni-kid-2.* source repositories. It replaces the older Google Doc / GitBook documentation (last meaningfully updated 2021–2025), correcting parts that had drifted from the live system. Use the left nav to drill into each component; the Gaps & Open Questions page tracks what still needs confirmation.
What the system does
Macaroni KID runs hundreds of localized "town" editions, each a community newsletter and event calendar maintained by a local publisher. The platform handles the full content lifecycle:
- Content creation & publishing — publishers write articles, guides, and events; the system clones and shares content across towns and auto-publishes newsletters on a schedule.
- Public website — every town has a public site (its own subdomain) showing articles, events, business directories, and guides.
- Email newsletters — scheduled and dynamic newsletters are rendered and sent to subscribers, with deliverability handled through multiple email providers.
- Search — articles, businesses, and events are indexed into AWS OpenSearch for fast lookup across the network.
- Administration — staff and publishers manage towns, content, subscribers, and reporting through an admin panel.
The four repositories
Public Website
macaroni-kid-2.web2
The public-facing site. PHP 7.4 on Apache, server-rendered, built with Gulp/Sass. Serves every town subdomain and tracks pageviews back to the API.
Explore the website →REST API
macaroni-kid-2.api
The core backend. Node.js 18 + Express + Mongoose over MongoDB, with JWT auth, OpenSearch indexing, and a separate worker process for cron jobs and queues.
Explore the API →Admin Panel
macaroni-kid-2.admin-panel
The internal management UI. An AngularJS 1.5 single-page app (Angular Material), built with Gulp/Bower and served as a container behind nginx.
Explore the admin panel →Orchestration
macaroni-kid-2.docker-compose
Docker Compose definitions that wire the API, admin, web, and a local MongoDB together for development and reference production builds.
Explore environments →By the numbers
Technology stack at a glance
| Layer | Technology | Notes |
|---|---|---|
| Public website | PHP 7.4, Apache | Server-rendered; Gulp + Sass build; git-deploy.php webhook deploy |
| API | Node.js 18.20.7, Express, Mongoose | v1.5.8; JWT/passport auth; PM2 cluster (4 instances); Sentry |
| Worker | Node.js (same repo) | Separate process; node-cron jobs + queues; Dockerfile.worker |
| Admin panel | AngularJS 1.5, Angular Material 1.1.4 | Gulp 3 + Bower build on Node 8; hosted on Heroku (branch CI/CD) |
| Database | MongoDB 3.4 | Accessed through Mongoose; primary system of record |
| Cache / queues | Redis (ioredis) | Caching and background job queues |
| Search | AWS OpenSearch | Three domains: Article, Business, Event |
| Object storage | Amazon S3 | Image and asset uploads |
| SendGrid, AWS SES, Ongage | Transactional + marketing; Fresh Address for validation | |
| Hosting | Linode | API/web on Linode; CloudFlare in front; admin containerized |
analytics.macaronikid.com) is being decommissioned.