The Unframed Story

The -ITYs

Most codebases optimize for short-term shipping speed and treat quality attributes as nice-to-haves. Unframed treats them as load-bearing walls — each one is enforced by convention, tooling, and code review. Several of these are measured by deterministic scoring algorithms that run against the codebase and produce repeatable results.

• Testability. Testable code isn't about writing more tests — it's about designing code that's easy to test. Constructor injection means every dependency is swappable with fakes or mocks. Interface Segregation keeps contracts small so tests only depend on what they need. Single Responsibility means each class does one thing, so each test exercises one behavior. Tagged tests let you compose test suites on the fly — A-tier vs. B-tier, unit vs. integration, authentication vs. authorization, fast pure-logic vs. needs-database. Run exactly the tests that matter for your change in seconds. Transaction-wrapped tests auto-roll back — zero shared state, zero cleanup code, zero beforeAll(). Tests run twice: random order then normal. If order matters, the tests are broken.
• Modularity. 270+ services, each with a dedicated interface file and an Impl file. Manual DI wiring — no framework, no decorators, no classpath scanning. Every module is self-contained: co-located interface, implementation, and types. Swap any piece without ripple effects.
• Maintainability. Single Responsibility enforced — one reason to change per class. Co-location means related code lives together. Interface-first design means you modify implementations, not contracts. The codebase gets easier to maintain as it grows, not harder.
• Understandability. No abbreviations. SystemConfigurationService, not SysConfigSvc. Every method starts with an action verb. Variable names match class names. 1,200+ lines of PHILOSOPHY.md, 780+ lines of TECHNICAL_GUIDE.md, 160+ conversation-starter docs.
• Upgradeability. Only 27 external runtime dependencies — each one chosen deliberately, each one replaceable. No ORM migration chains to manage. No framework version lock-in. Vendor abstractions behind interfaces mean upgrading or swapping a provider is a one-file change.
• Debuggability. Leave-in logging with named loggers, method prefixes, and the Greppable Log Prefix Rule. Every log line traces back to its source with a single grep. Objects serialized with d4l() — no [object Object], no missing context.
• Readability. File names match what's inside. HoldemGameRoomService.ts contains HoldemGameRoomService. No clever tricks, no magic, no indirection that requires a debugger to follow. Code reads like prose, not a puzzle.
• Clarity. Every logger is named module.ClassName. Every log line is prefixed with its method name. Log text is unique before interpolation (GLPR). No ambiguity about what happened, where, or why.
• Tenability. Every architectural decision is documented and defensible. PHILOSOPHY.md explains the why. TECHNICAL_GUIDE.md explains the how. Conversation-starter docs capture the tradeoffs considered and rejected. No decisions by accident — only decisions by intent.
• Sustainability. No tech debt treadmill. The database schema is reborn from empty hundreds of times via factory-reset — if it can't be rebuilt cleanly, it's fixed. Leave-in logging means you never re-add instrumentation. Interface-first means you never rewrite callers when implementations change.
• Repeatability. Deterministic tests, reproducible builds, factory-reset from empty. The database is rebuilt from migrations and seed data — not nursed along with manual patches. Codebase quality scores are computed by algorithms, not opinions. Same inputs, same outputs, every time.
• Fixability. When something breaks, you find it fast. Greppable log prefixes, named loggers, method-level tracing, and d4l() serialization mean the log output tells you what broke, where, and why — before you open an editor.
• Pay-it-forward-ility. Today's work makes tomorrow's easier. Leave-in logging prevents the next person from re-debugging the same problem. Interface-first design means the next feature plugs into existing contracts. Every conversation-starter doc saves a future engineer from re-deriving the same conclusion.
• Traceability. From a production log line, you can follow the path to the exact method, the exact service, the exact request. Three exception types with zero ambiguity: NotFoundException, ProgrammerErrorException, StateException. Every event flows through the Happening system with who, what, when, where.
• Onboardability. README, PHILOSOPHY.md, TECHNICAL_GUIDE.md, CLAUDE.md, and 160+ conversation-starter documents. The codebase explains itself. A new engineer — or an LLM — can get productive without a walkthrough.
• Teachability. The codebase is its own curriculum. Consistent patterns everywhere — learn how one service works and you know how all 270+ work. Interface → Impl → DI wiring → Controller. The same shape, every time, in every module.
• Swappability. Every service is behind an interface. Every dependency is injected through constructors. The DI container is the only file that knows which Impl backs which interface. Swap Postgres for DynamoDB, swap Claude for GPT, swap SMTP for a test double — one file changes, zero consumers notice. The plain-function pattern stops working when you need testability, swappability, or multi-environment configuration. Interfaces + DI is the answer.
• Agility. Program to interfaces, not implementations. No framework lock-in, no database lock-in, no cloud lock-in. Pivot without being weighed down. The codebase bends without breaking.
• Reusability. The Discussable pattern makes any entity commentable. ResourceTag makes any entity taggable. The Happening system tracks events on anything. Build a pattern once, use it across every module.
• Maturity. Battle-tested in production with real users and real data. No experimental frameworks, no resume-driven architecture. Every dependency is proven. Resources go toward value creation, not R&D novelty.
• Extensibility. Add features without rewriting. New modules plug into existing infrastructure — authentication, logging, DI, testing, tagging, discussions — all available from day one. The 18th feature is as easy to add as the 3rd.
• Simplicity. Only 27 external runtime dependencies. Raw SQL instead of an ORM. Manual DI instead of a framework. No Docker, no Kubernetes, no microservices. One server, one database, one codebase. Complexity is the enemy — every added layer must justify its existence.
• Developer Productivity & Enjoyability. Minutes to start coding, not days fighting infrastructure. No LocalStack, no Docker Compose, no environment babysitting. make run-dev and you're building features. Development should be enjoyable, not a chore.
• Robustability. The codebase handles failure gracefully. Programmer errors crash immediately — no silent corruption. Operational errors are caught and handled deterministically. The database schema rebuilds from empty. The test suite runs in random order. If something can break, it breaks loudly, early, and in a way you can fix.
• Usability. Progressive disclosure means users only see what applies to them. No "sign up vs. sign in" decision — enter your email and the system figures it out. Navigation adapts to who you are. Features reveal themselves as you use them, not all at once in an overwhelming dashboard.
• Positivity. The codebase is a place people want to work. Consistent patterns reduce cognitive load. No tribal knowledge required. No landmines. No "don't touch that file." When every module follows the same shape, confidence replaces anxiety — and confident developers ship better code.
• Productivity. The architecture gets out of your way. New features plug into existing infrastructure — authentication, logging, DI, testing, tagging, discussions — all available from day one. The 18th feature is as easy to add as the 3rd. A developer's time goes toward solving the problem, not fighting the codebase.

Leave-In Logging

The industry pattern is: add logging to debug, fix the bug, remove the logging. We think that's backwards.

• Every log statement is written as if it will be in production forever — because it will be.
• Correct log level from the start. No "temporary" console.log. No upgrading debug to info just to see output.
• Every logger is named after its module. Every log line is prefixed with the method that wrote it.
• Objects are serialized with d4l() — no [object Object], no accidental PII leaks.
• GLPR (Greppable Log Prefix Rule): log text is unique before interpolation, so you can grep any line back to its source.
• The logging you add while debugging a problem is the logging that prevents the next person from needing to debug it.

Testing

Not "we have tests." Every test is designed to be trustworthy.

• Every test runs in a transaction that auto-rolls back. No shared state. No cleanup code. No flaky tests.
• Tests run in random order. If order matters, your tests are broken.
• Zero beforeAll() in the entire codebase — not one. Each test sets up exactly what it needs.
• Test tags (speed:purelogic, needsRdbms) let you run the right subset in seconds.

Exceptions

Two kinds of errors, two handling strategies, zero ambiguity.

• Programmer errors crash immediately. They are never caught. If your code has a bug, you find out now — not three layers up.
• Operational errors (not found, bad state) are handled deterministically with normalized exception types.
• Three types: NotFoundException, ProgrammerErrorException, StateException. That's it.

Program to an Interface

Not just "we use interfaces." Every service has one, and nothing depends on a concrete class.

• 270+ services. Every one has a dedicated interface file and an Impl file. No exceptions.
• Dependency injection is manual and explicit — no framework, no decorators, no classpath scanning.
• You can swap any implementation without touching the code that uses it.

Security

Not bolted on after a breach. Designed in from line one.

• AES-256-GCM encryption at rest. HKDF key derivation. Encrypt-then-MAC for cookies and tokens.
• PII access audit log — every read of sensitive data is recorded.
• Parameterized queries everywhere. No string concatenation in SQL. Ever.

IDs & Time

Two things most codebases get wrong early and pay for forever.

• Right ID for the job: UUID v7 for database rows (time-sortable), nanoid for URLs, slugs for humans.
• Branded types enforce compile-time distinction — UserId is not a PrincipalId, even though both are strings.
• DateProvider service — no raw new Date(). Time is injectable and testable from day one.
• Timezone-aware from the start. Not retrofitted after the first international user.

Semantic Naming

Most codebases abbreviate everything. Then new engineers spend their first month decoding tribal shorthand.

• No abbreviations. TransactionContext, not txCtx. SystemConfigurationService, not SysConfigSvc.
• Every method name begins with an action verb: createUser, findByEmail, calculateFreeTime.
• Variable names match class names: TransactionContext → transactionContext. No guessing what anything is.
• File names match what's inside: HoldemGameRoomService.ts contains HoldemGameRoomService. Always.

Observability (OTEL)

Most teams bolt on observability after something breaks in production. Here it's built into the event model.

• The Happening system is OpenTelemetry-aligned from the ground up — structured events with automatic enrichment.
• Every happening captures context: who, what, when, where, from which IP, which session, which request.
• Multi-backend fan-out: one event goes to Postgres, S3, BigQuery, Kafka, Google Sheets, or Mixpanel — your choice.
• OTEL traces captured to S3 for long-term analysis. Not just dashboards — queryable data you own.

Analytics

Most analytics live in a third-party dashboard you can look at but can't use. Ours live in the database where your code runs.

• Own-your-data: analytics land in Postgres, BigQuery, S3, and DynamoDB — not just a vendor's SaaS dashboard.
• Use analytics in business logic. "Show users who were active this week" is a SQL query, not an API call to Mixpanel.
• Stat engine with capture, filtering, downsampling, and SVG sparkline rendering — all in-house.
• Beacon system: tracking pixels, short URLs, unique visitor tokens, self-view detection — built in, not bolted on.

Commodity LLM Connectivity

Most codebases treat AI as a feature to add later. Here it's plumbing — available everywhere, from day one.

• Four providers wired in: Claude, ChatGPT, Bedrock, Gemini. Swap models without changing calling code.
• Structured output extraction — JSON-ify any LLM response into typed objects your services can use.
• Talk-to-my-data: natural language queries against your own database. Not a demo — a production CLI tool.
• AI is a service dependency like any other: injected, interfaced, testable, swappable.

Progressive Disclosure

Most apps show everything to everyone and hope users figure out what's relevant. Progressive disclosure means users only see what applies to them, when it applies to them.

• Login flow is progressive: enter your email, we figure out whether you're new or returning, then show the right next step. No "sign up vs. sign in" decision for the user to make.
• Navigation adapts: anonymous visitors see public content. Logged-in users see their tools. Admins see admin controls. Same URL, different experience.
• Collections and features reveal themselves as you use them — not all at once in an overwhelming dashboard.
• The pattern is baked into the framework, not bolted on per-feature. Any new feature inherits progressive disclosure automatically via the authentication and authorization layers.

Vendor Independence

The last two decades coached us to trade build-it for buy-it. We traded moderate development costs for overhyped "solutions as services" — which come with expensive integration, orchestration, vendor lock-in, and a convenience charge.

What have you been convinced you need just to get started? Auth0 for login. Mixpanel for analytics. Google Analytics for tracking. Elasticsearch for search. New Relic or Datadog for monitoring. SendGrid for email. LaunchDarkly for feature flags. Sentry for error tracking. Calendly for scheduling. Stripe Billing before you have revenue. Redis and Sidekiq before you have traffic. MongoDB Atlas or Supabase because "Postgres doesn't scale." Segment to glue it all together. Docker and Kubernetes before you have a second server. Terraform before you have a second environment. And a DevOps hire to keep the lights on.

Unframed replaces all of them. Authentication, analytics, email, scheduling, feature flags, error handling, job queues, observability, event tracking, search — it's all here, already built, already tested, already working. On a single Linux server and Postgres.

And it can scale to millions of users before you need to consider what's next. Unframed is the perfect Product-Market Fit Finder — the codebase that lets you focus on finding your market instead of stitching together vendors.

• No AWS lock-in. S3, SES, DynamoDB, and Bedrock are used but abstracted behind interfaces — swap the implementation, keep the contract.
• No framework lock-in. Express is the HTTP layer, but business logic doesn't know or care.
• No database lock-in. Raw SQL with a thin repository layer. No ORM migration path to manage.
• Only 27 external runtime dependencies. You can read the full list in under a minute and understand every one.

Database Schema — Reborn from Empty, Hundreds of Times

The standard approach: write your initial schema, then accumulate ALTER TABLE migrations forever. After a year you have 200 migration files and nobody knows what the schema actually looks like without running them all.

• One canonical schema file. Every change — column rename, new table, constraint tweak — is made directly in that file, then make factory-reset rebuilds the entire database from empty.
• This schema has been recreated from scratch hundreds of times. Each rebuild is a clean CREATE TABLE, not an ALTER stapled onto history. The schema you read today is the distilled result of hundreds of iterations, each one starting from zero.
• Even production can be rebuilt: precious data is backed up, the schema is recreated clean, data is restored. This isn't theory — we do it routinely.
• The result: the schema reads like documentation. No archaeological layers. No "this column used to be called X." No migration that adds a column and a later migration that renames it.
• GENERATED ALWAYS AS computed columns. Trigger-managed timestamps. UUID v7 primary keys. Proper normalization. All from day one — not retrofitted.

PII Encryption at Rest

Most startups say "we'll add encryption when we need to comply with something." We encrypted PII fields the day they were first stored.

• AES-256-GCM with HKDF key derivation — not "we'll add encryption later."
• PII access audit log — every read of sensitive data is recorded, not just writes.
• No compliance requirement forced this. We did it because it was the right thing to do with other people's data.

Pseudonymized Ownership

The spending tracker knows who owns each transaction. But it doesn't store that relationship in the obvious way.

• HMAC-SHA256 pseudonyms instead of raw user IDs. Even if the database leaks, you can't trivially map transactions to people.
• The pseudonym system is built into the data model — not a privacy layer bolted on after a regulator asked questions.
• Most startups don't think about this until they're preparing for SOC 2. We built it before we had our second user.

Spending Tracker

Real Chase and Citibank statements. Real grocery spending. Real subscriptions.

• The recurring payment detection feature exists because we looked at our own spending page and thought "I know I'm paying for more subscriptions than this shows."
• Receipt parsing was built by scanning actual grocery receipts from weekly runs to Jewel-Osco.
• Merchant categorization was refined by looking at our own uncategorized charges and asking "why didn't this get tagged?"

Vault

The team's actual passwords, API keys, and secrets live in the Unframed vault.

• AES-256-GCM encryption with client-side key derivation — not because a spec required it, but because our passwords are in there.
• We didn't outsource to 1Password or Bitwarden. We built it, we use it, we trust it with our own credentials.

Card Games

Hold'em and Up The River — built, then played with friends on game night.

• The bot AI (Tight Teresa, Calling Carl) exists because we needed opponents when nobody else was online.
• The WebSocket reconnection logic was debugged during an actual poker game when someone's phone went to sleep.
• Starting chip counts, blind structures, and game pacing were all tuned by playing real hands — not by guessing at parameters.

Everything Else

It's not just the marquee features. The small tools get used daily too.

• 700+ real bookmarks in production. Not test data — actual links saved and retrieved.
• The CLI tool manages production deploys, sends notifications, and runs seeds. We use it every day.
• Telegram notifications tell us when deploys finish while we're away from the desk. Built because we needed it.
• The Happenings dashboard is read daily. Google Sheets capture exists because we wanted analytics in a spreadsheet we already had open.

14 Capabilities We Own

Each of these is a line item on someone else's vendor bill. For Unframed, they're just code we wrote and own outright.

• Authentication — scrypt passwords, passwordless tokens, transparent auth. Not Auth0 ($35-240/mo).
• Monitoring & Observability — OTEL traces to S3, structured logging, health checks. Not Datadog ($100-300/mo).
• Product Analytics — Happening system + Postgres + multi-backend fan-out. Not Mixpanel ($280/mo at 2M events).
• Error Tracking — structured logging + OTEL spans. Not Sentry ($29/mo).
• Email — Nodemailer + AWS SES. Not SendGrid ($20-90/mo).
• Feature Flags — environment-driven FeatureFlagService. Not LaunchDarkly ($40-60/mo).
• Job Queues — SolidQueue on Postgres. Not managed Redis + Sidekiq ($15-50/mo).
• Search — Postgres full-text search with GIN indexes. Not Algolia ($50-200/mo).
• Password Management — Vault with AES-256-GCM. Not 1Password ($16/mo).
• CRM — contact manager + outreach tracking. Not HubSpot ($40-60/mo).
• Scheduling — Google Calendar integration. Not Calendly ($24/mo).
• Notifications — Telegram + SMS + in-app. Not Twilio + OneSignal ($10-30/mo).
• CI/CD — Makefile + rsync + systemd. Not CircleCI ($15-30/mo).
• Container Orchestration — single Linux server + systemd. Not EKS ($73/mo for the control plane alone).

The Economics

Unframed's total infrastructure cost: ~$50/month. One EC2 instance, AWS SES for email, S3 for storage.

• At small scale (2 people, low usage): the vendor bill would be ~$280/mo. Annual savings: ~$2,700.
• At moderate scale (10K users): ~$1,150/mo in vendor costs. Annual savings: ~$13,000.
• At growth scale (100K+ users): vendors alone run $3,000-5,000/mo. Annual savings: $33,000-57,000.
• SaaS costs scale with success — the more users you get, the more you pay vendors for the privilege of serving them. Owned infrastructure stays flat until you genuinely need to scale.

Postgres Scales Further Than You Think

"Postgres doesn't scale" is vendor marketing. OpenAI serves 800M users on a single-primary Postgres deployment. Figma scaled to 4M users on Postgres before needing changes.

• A single well-tuned RDS instance handles 500K-1M+ registered users before any homegrown solution needs revisiting.
• At $250/mo (db.r6g.large), Postgres handles 200K registered users with all of Unframed's services running fine.
• The first thing to upgrade — job queues to Redis — costs $15-50/mo and is a swap behind an existing interface.
• The architecture is designed to let components graduate independently. Everything is behind interfaces — when something outgrows Postgres, you swap the implementation, not the architecture.

Why These Features Exist

Every feature in Alito exists for one of three reasons:

• Overpaid for it elsewhere. Calendly costs $20/month with feature gaps. 1Password costs $16/month. HubSpot costs $40/month. These are tools I was already paying for — and paying too much for things that should be simple.
• Inadequate elsewhere. The SaaS version had limitations or workflows that didn't fit. The spending tracker exists because nothing handled family spending across multiple banks the way we needed.
• Didn't merit a standalone product. A bookmark manager isn't a company. A typing practice tool isn't a product. But they're useful tools that any platform should be able to spin up in a day — if the foundation is there.

Features as a Forcing Function

Alito's features aren't just dogfooding. They're a forcing function for the modularity — all the -ilities — in Unframed.

• To prove the encryption layer works, you need a vault that stores real passwords. Ours does.
• To prove the WebSocket layer works, you need a real-time multiplayer game people actually play. We play Hold'em on it.
• To prove the ledger works, you need a spending tracker importing real bank statements. We import ours weekly.
• Without Alito, Unframed's interfaces would be theoretical. With Alito, every interface has been exercised, every pattern stress-tested, every module proven in production.

The Map

You can draw a direct line from each Alito feature to the Unframed modules it exercises:

Plus cross-cutting patterns exercised by every feature: authentication, leave-in logging, branded types, interface-first DI, transaction-wrapped testing, universal resource tagging, and the Discussable pattern.