citycontacts: The AI-Optimized SaaS Monolith
How a Rails 8 boilerplate uses embedded rules and a custom CLI to turn Claude and Cursor into your founding engineering team.
a Rails 8 template by @ryanckulp, created to ship SaaS apps quickly.
- Citycontacts (Speedrail) embeds AI instructions directly into the repo, treating LLMs as primary collaborators rather than mere code generators.
- A custom CLI acts as a meta-generator, instantly renaming namespaces and directories to eliminate boilerplate residue.
- The architecture rejects microservices, favoring a 'Majestic Monolith' approach with Rails 8, Stripe Embedded Checkout, and integrated scraping services for maximum developer velocity.
The AI Co-Founder's Onboarding Doc
For decades, software boilerplates have targeted a single audience: human developers. They exist to save keystrokes, providing a pre-configured starting line. citycontacts, a Rails 8 template built on the Speedrail architecture, fundamentally shifts this paradigm. It is written to onboard an artificial intelligence.
The repository includes specific files like .cursor/rules/ruby.mdc and CLAUDE.md. These aren't standard READMEs; they are behavioral guidelines for autonomous agents. By encoding architectural decisions—such as keeping controllers thin and delegating logic to service objects—the boilerplate ensures that when an LLM generates new features, it mimics the original author's exact style and intent.
The DNA Rewrite
A recurring problem with cloned templates is the lingering residue of the original project's namespace. Manually hunting down and replacing generic names in configuration files is tedious and error-prone. citycontacts solves this with a custom CLI tool: bin/speedrail.
This binary acts as a meta-generator. Running a single command surgically rewrites the application's DNA, instantly renaming namespaces, directories, and configuration files to transform the generic template into a unique product.
The Majestic, Pragmatic Monolith
Beneath the AI optimizations lies a fiercely pragmatic Rails 8 monolith. It actively rejects the complexity of microservices, opting instead to bundle everything a solopreneur needs into a single repository. This includes Stripe Embedded Checkout, which keeps users on-site for better conversion, and a robust Active Admin back-office.
The application also features an integrated data-mining engine. The ApifyScraperService and ScrapeCreatorsService interface with third-party APIs to extract location data from social media profiles. Rather than relying on heavy NLP models, the system uses simple Regex pattern matching to parse bios—a "good enough for MVP" philosophy that prioritizes speed.
The Velocity Trade-Off
Speedrail is highly opinionated. It dictates the use of Tailwind CSS, Devise for authentication, and Pretender for user impersonation. This lack of flexibility is a deliberate trade-off. By removing micro-decisions, it allows the developer—and their AI agents—to focus entirely on business logic.
| Feature | citycontacts (Speedrail) | Traditional Rails Starters |
|---|---|---|
| Target Audience | AI Agents & Solopreneurs | Human Development Teams |
| Setup Process | 1-Click CLI Rename | Manual Find & Replace |
| AI Readiness | Embedded .cursor/rules | None |
| Architecture | Highly Opinionated Monolith | Flexible / Modular |