Compare commits
8 Commits
4f37a72d7b
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
| eb12471941 | |||
| 60643409f6 | |||
| 5a8c0028d7 | |||
| f7e6e56aca | |||
| cd19a32be5 | |||
| 478305bc4f | |||
| 421628d49e | |||
| a0043fd475 |
1
.go-version
Normal file
1
.go-version
Normal file
@@ -0,0 +1 @@
|
|||||||
|
1.23.6
|
||||||
@@ -94,8 +94,8 @@ This ensures consistent tooling versions across the team without system-wide ins
|
|||||||
|
|
||||||
## Platform Requirements
|
## Platform Requirements
|
||||||
|
|
||||||
Linux x86_64 only (currently). Requires:
|
Linux or macOS on x86_64. Requires:
|
||||||
- Modern libc for Go binaries
|
- Modern libc for Go binaries (Linux)
|
||||||
- docker compose (for full stack)
|
- docker compose (for full stack)
|
||||||
- fd, shellcheck, shfmt (for development)
|
- fd, shellcheck, shfmt (for development)
|
||||||
|
|
||||||
|
|||||||
15
README.md
15
README.md
@@ -2,16 +2,13 @@ diachron
|
|||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
Is your answer to some of these questions "yes"? If so, you might like
|
|
||||||
diachron. (When it comes to that dev/test/prod one, hear us out first, ok?)
|
|
||||||
|
|
||||||
- Do you want to share a lot of backend and frontend code?
|
- Do you want to share a lot of backend and frontend code?
|
||||||
|
|
||||||
- Are you tired of your web stack breaking when you blink too hard?
|
- Are you tired of your web stack breaking when you blink too hard?
|
||||||
|
|
||||||
- Have you read [Taking PHP
|
- Have you read [Taking PHP
|
||||||
Seriously](https://slack.engineering/taking-php-seriously/) and wish you had
|
Seriously](https://slack.engineering/taking-php-seriously/) and do you wish
|
||||||
something similar for Typescript?
|
you had something similar for Typescript?
|
||||||
|
|
||||||
- Do you think that ORMs are not all that? Do you wish you had first class
|
- Do you think that ORMs are not all that? Do you wish you had first class
|
||||||
unmediated access to your database? And do you think that database
|
unmediated access to your database? And do you think that database
|
||||||
@@ -35,6 +32,9 @@ diachron. (When it comes to that dev/test/prod one, hear us out first, ok?)
|
|||||||
you're trying to fix? We're talking authentication, authorization, XSS,
|
you're trying to fix? We're talking authentication, authorization, XSS,
|
||||||
https, nested paths, all that stuff.
|
https, nested paths, all that stuff.
|
||||||
|
|
||||||
|
Is your answer to some of these questions "yes"? If so, you might like
|
||||||
|
diachron. (When it comes to that dev/test/prod one, hear us out first, ok?)
|
||||||
|
|
||||||
## Getting started
|
## Getting started
|
||||||
|
|
||||||
Different situations require different getting started docs.
|
Different situations require different getting started docs.
|
||||||
@@ -44,9 +44,8 @@ Different situations require different getting started docs.
|
|||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
To run diachron, you currently need to have a Linux box running x86_64 with a
|
To run diachron, you need Linux or macOS on x86_64. Linux requires a new
|
||||||
new enough libc to run golang binaries. Support for other platforms will come
|
enough libc to run golang binaries.
|
||||||
eventually.
|
|
||||||
|
|
||||||
To run a more complete system, you also need to have docker compose installed.
|
To run a more complete system, you also need to have docker compose installed.
|
||||||
|
|
||||||
|
|||||||
27
TODO.md
27
TODO.md
@@ -4,8 +4,33 @@
|
|||||||
- ⚠️ Huge task - needs breakdown before starting
|
- ⚠️ Huge task - needs breakdown before starting
|
||||||
|
|
||||||
|
|
||||||
|
- [ ] migrations, seeding, fixtures
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE SCHEMA fw;
|
||||||
|
CREATE TABLE fw.users (...);
|
||||||
|
CREATE TABLE fw.groups (...);
|
||||||
|
```
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE app.user_profiles (...);
|
||||||
|
CREATE TABLE app.customer_metadata (...);
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] flesh out `mgmt` and `develop` (does not exist yet)
|
||||||
|
|
||||||
|
4.1 What belongs in develop
|
||||||
|
|
||||||
|
- Create migrations
|
||||||
|
- Squash migrations
|
||||||
|
- Reset DB
|
||||||
|
- Roll back migrations
|
||||||
|
- Seed large test datasets
|
||||||
|
- Run tests
|
||||||
|
- Snapshot / restore local DB state (!!!)
|
||||||
|
|
||||||
|
`develop` fails if APP_ENV (or whatever) is `production`. Or maybe even
|
||||||
|
`testing`.
|
||||||
|
|
||||||
- [ ] Add default user table(s) to database.
|
- [ ] Add default user table(s) to database.
|
||||||
|
|
||||||
@@ -44,6 +69,8 @@
|
|||||||
necessary at all, with some sane defaults and an easy to use override
|
necessary at all, with some sane defaults and an easy to use override
|
||||||
mechanism
|
mechanism
|
||||||
|
|
||||||
|
- [ ] time library
|
||||||
|
|
||||||
- [ ] fill in the rest of express/http-codes.ts
|
- [ ] fill in the rest of express/http-codes.ts
|
||||||
|
|
||||||
- [ ] fill out express/content-types.ts
|
- [ ] fill out express/content-types.ts
|
||||||
|
|||||||
125
docs/commands.md
Normal file
125
docs/commands.md
Normal file
@@ -0,0 +1,125 @@
|
|||||||
|
# The Three Types of Commands
|
||||||
|
|
||||||
|
This framework deliberately separates *how* you interact with the system into three distinct command types. The split is not cosmetic; it encodes safety, intent, and operational assumptions directly into the tooling so that mistakes are harder to make under stress.
|
||||||
|
|
||||||
|
The guiding idea: **production should feel boring and safe; exploration should feel powerful and a little dangerous; the application itself should not care how it is being operated.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Application Commands (`app`)
|
||||||
|
|
||||||
|
**What they are**
|
||||||
|
Commands defined *by the application itself*, for its own domain needs. They are not part of the framework, even though they are built on top of it.
|
||||||
|
|
||||||
|
The framework provides structure and affordances; the application supplies meaning.
|
||||||
|
|
||||||
|
**Core properties**
|
||||||
|
|
||||||
|
* Express domain behavior, not infrastructure concerns
|
||||||
|
* Safe by definition
|
||||||
|
* Deterministic and repeatable
|
||||||
|
* No environment‑dependent semantics
|
||||||
|
* Identical behavior in dev, staging, and production
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
* Handling HTTP requests
|
||||||
|
* Rendering templates
|
||||||
|
* Running background jobs / queues
|
||||||
|
* Sending emails triggered by application logic
|
||||||
|
|
||||||
|
**Non‑goals**
|
||||||
|
|
||||||
|
* No schema changes
|
||||||
|
* No data backfills
|
||||||
|
* No destructive behavior
|
||||||
|
* No operational or lifecycle management
|
||||||
|
|
||||||
|
**Rule of thumb**
|
||||||
|
If removing the framework would require rewriting *how* it runs but not *what* it does, the command belongs here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Management Commands (`mgmt`)
|
||||||
|
|
||||||
|
**What they are**
|
||||||
|
Operational, *production‑safe* commands used to evolve and maintain a live system.
|
||||||
|
|
||||||
|
These commands assume real data exists and must not be casually destroyed.
|
||||||
|
|
||||||
|
**Core properties**
|
||||||
|
|
||||||
|
* Forward‑only
|
||||||
|
* Idempotent or safely repeatable
|
||||||
|
* Designed to run in production
|
||||||
|
* Explicit, auditable intent
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
* Applying migrations
|
||||||
|
* Running seeders that assert invariant data
|
||||||
|
* Reindexing or rebuilding derived data
|
||||||
|
* Rotating keys, recalculating counters
|
||||||
|
|
||||||
|
**Design constraints**
|
||||||
|
|
||||||
|
* No implicit rollbacks
|
||||||
|
* No hidden destructive actions
|
||||||
|
* Fail fast if assumptions are violated
|
||||||
|
|
||||||
|
**Rule of thumb**
|
||||||
|
If you would run it at 3am while tired and worried, it must live here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Development Commands (`develop`)
|
||||||
|
|
||||||
|
**What they are**
|
||||||
|
Sharp, *unsafe by design* tools meant exclusively for local development and experimentation.
|
||||||
|
|
||||||
|
These commands optimize for speed, learning, and iteration — not safety.
|
||||||
|
|
||||||
|
**Core properties**
|
||||||
|
|
||||||
|
* Destructive operations allowed
|
||||||
|
* May reset or mutate large amounts of data
|
||||||
|
* Assume a clean or disposable environment
|
||||||
|
* Explicitly gated in production
|
||||||
|
|
||||||
|
**Examples**
|
||||||
|
|
||||||
|
* Dropping and recreating databases
|
||||||
|
* Rolling migrations backward
|
||||||
|
* Loading fixtures or scenarios
|
||||||
|
* Generating fake or randomized data
|
||||||
|
|
||||||
|
**Safety model**
|
||||||
|
|
||||||
|
* Hard to run in production
|
||||||
|
* Requires explicit opt‑in if ever enabled
|
||||||
|
* Clear, noisy warnings when invoked
|
||||||
|
|
||||||
|
**Rule of thumb**
|
||||||
|
If it would be irresponsible to run against real user data, it belongs here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why This Split Matters
|
||||||
|
|
||||||
|
Many frameworks blur these concerns, leading to:
|
||||||
|
|
||||||
|
* Fearful production operations
|
||||||
|
* Overpowered dev tools leaking into prod
|
||||||
|
* Environment‑specific behavior and bugs
|
||||||
|
|
||||||
|
By naming and enforcing these three command types:
|
||||||
|
|
||||||
|
* Intent is visible at the CLI level
|
||||||
|
* Safety properties are architectural, not cultural
|
||||||
|
* Developers can move fast *without* normalizing risk
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## One‑Sentence Summary
|
||||||
|
|
||||||
|
> **App commands run the system, mgmt commands evolve it safely, and develop commands let you break things on purpose — but only where it’s allowed.**
|
||||||
37
docs/concentric-circles.md
Normal file
37
docs/concentric-circles.md
Normal file
@@ -0,0 +1,37 @@
|
|||||||
|
Let's consider a bullseye with the following concentric circles:
|
||||||
|
|
||||||
|
- Ring 0: small, simple systems
|
||||||
|
- Single jurisdiction
|
||||||
|
- Email + password
|
||||||
|
- A few roles
|
||||||
|
- Naïve or soft deletion
|
||||||
|
- Minimal audit needs
|
||||||
|
|
||||||
|
- Ring 1: grown-up systems
|
||||||
|
- Long-lived data
|
||||||
|
- Changing requirements
|
||||||
|
- Shared accounts
|
||||||
|
- GDPR-style erasure/anonymization
|
||||||
|
- Some cross-border concerns
|
||||||
|
- Historical data must remain usable
|
||||||
|
- “Oops, we should have thought about that” moments
|
||||||
|
|
||||||
|
- Ring 2: heavy compliance
|
||||||
|
- Formal audit trails
|
||||||
|
- Legal hold
|
||||||
|
- Non-repudiation
|
||||||
|
- Regulatory reporting
|
||||||
|
- Strong identity guarantees
|
||||||
|
- Jurisdiction-aware data partitioning
|
||||||
|
|
||||||
|
- Ring 3: banking / defense / healthcare at scale
|
||||||
|
- Cryptographic auditability
|
||||||
|
- Append-only ledgers
|
||||||
|
- Explicit legal models
|
||||||
|
- Independent compliance teams
|
||||||
|
- Lawyers embedded in engineeRing
|
||||||
|
|
||||||
|
diachron is designed to be suitable for Rings 0 and 1. Occasionally we may
|
||||||
|
look over the fence into Ring 2, but it's not what we've principally designed
|
||||||
|
for. Please take this framing into account when evaluating diachron for
|
||||||
|
greenfield projects.
|
||||||
142
docs/freedom-hacking-and-responsibility.md
Normal file
142
docs/freedom-hacking-and-responsibility.md
Normal file
@@ -0,0 +1,142 @@
|
|||||||
|
# Freedom, Hacking, and Responsibility
|
||||||
|
|
||||||
|
This framework is **free and open source software**.
|
||||||
|
|
||||||
|
That fact is not incidental. It is a deliberate ethical, practical, and technical choice.
|
||||||
|
|
||||||
|
This document explains how freedom to modify coexists with strong guidance about *how the framework is meant to be used* — without contradiction, and without apology.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The short version
|
||||||
|
|
||||||
|
* This is free software. You are free to modify it.
|
||||||
|
* The framework has documented invariants for good reasons.
|
||||||
|
* You are encouraged to explore, question, and patch.
|
||||||
|
* You are discouraged from casually undermining guarantees you still expect to rely on.
|
||||||
|
* Clarity beats enforcement.
|
||||||
|
|
||||||
|
Freedom with understanding beats both lock-in and chaos.
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Your Freedom
|
||||||
|
|
||||||
|
You are free to:
|
||||||
|
|
||||||
|
* study the source code
|
||||||
|
* run the software for any purpose
|
||||||
|
* modify it in any way
|
||||||
|
* fork it
|
||||||
|
* redistribute it, with or without changes
|
||||||
|
* submit patches, extensions, or experiments
|
||||||
|
|
||||||
|
…subject only to the terms of the license.
|
||||||
|
|
||||||
|
These freedoms are foundational. They are not granted reluctantly, and they are not symbolic. They exist so that:
|
||||||
|
|
||||||
|
* you can understand what your software is really doing
|
||||||
|
* you are not trapped by vendor control
|
||||||
|
* the system can outlive its original authors
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Freedom Is Not the Same as Endorsement
|
||||||
|
|
||||||
|
While you are free to change anything, **not all changes are equally wise**.
|
||||||
|
|
||||||
|
Some parts of the framework are carefully constrained because they encode:
|
||||||
|
|
||||||
|
* security assumptions
|
||||||
|
* lifecycle invariants
|
||||||
|
* hard-won lessons from real systems under stress
|
||||||
|
|
||||||
|
You are free to violate these constraints in your own fork.
|
||||||
|
|
||||||
|
But the framework’s documentation will often say things like:
|
||||||
|
|
||||||
|
* “do not modify this”
|
||||||
|
* “application code must not depend on this”
|
||||||
|
* “this table or class is framework-owned”
|
||||||
|
|
||||||
|
These statements are **technical guidance**, not legal restrictions.
|
||||||
|
|
||||||
|
They exist to answer the question:
|
||||||
|
|
||||||
|
> *If you want this system to remain upgradeable, predictable, and boring — what should you leave alone?*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Intended Social Contract
|
||||||
|
|
||||||
|
The framework makes a clear offer:
|
||||||
|
|
||||||
|
* We expose our internals so you can learn.
|
||||||
|
* We provide explicit extension points so you can adapt.
|
||||||
|
* We document invariants so you don’t have to rediscover them the hard way.
|
||||||
|
|
||||||
|
In return, we ask that:
|
||||||
|
|
||||||
|
* application code respects documented boundaries
|
||||||
|
* extensions use explicit seams rather than hidden hooks
|
||||||
|
* patches that change invariants are proposed consciously, not accidentally
|
||||||
|
|
||||||
|
Nothing here is enforced by technical locks.
|
||||||
|
|
||||||
|
It is enforced — insofar as it is enforced at all — by clarity and shared expectations.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hacking Is Welcome
|
||||||
|
|
||||||
|
Exploration is not just allowed; it is encouraged.
|
||||||
|
|
||||||
|
Good reasons to hack on the framework include:
|
||||||
|
|
||||||
|
* understanding how it works
|
||||||
|
* evaluating whether its constraints make sense
|
||||||
|
* adapting it to unfamiliar environments
|
||||||
|
* testing alternative designs
|
||||||
|
* discovering better abstractions
|
||||||
|
|
||||||
|
Fork it. Instrument it. Break it. Learn from it.
|
||||||
|
|
||||||
|
Many of the framework’s constraints exist *because* someone once ignored them and paid the price.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Patches, Not Patches-in-Place
|
||||||
|
|
||||||
|
If you discover a problem or a better design:
|
||||||
|
|
||||||
|
* patches are welcome
|
||||||
|
* discussions are welcome
|
||||||
|
* disagreements are welcome
|
||||||
|
|
||||||
|
What is discouraged is **quietly patching around framework invariants inside application code**.
|
||||||
|
|
||||||
|
That approach:
|
||||||
|
|
||||||
|
* obscures intent
|
||||||
|
* creates one-off local truths
|
||||||
|
* makes systems harder to reason about
|
||||||
|
|
||||||
|
If the framework is wrong, it should be corrected *at the framework level*, or consciously forked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why This Is Not a Contradiction
|
||||||
|
|
||||||
|
Strong opinions and free software are not enemies.
|
||||||
|
|
||||||
|
Freedom means you can change the software.
|
||||||
|
|
||||||
|
Responsibility means understanding what you are changing, and why.
|
||||||
|
|
||||||
|
A system that pretends every modification is equally safe is dishonest.
|
||||||
|
|
||||||
|
A system that hides its internals to prevent modification is hostile.
|
||||||
|
|
||||||
|
This framework aims for neither.
|
||||||
|
|
||||||
27
docs/groups-and-roles.md
Normal file
27
docs/groups-and-roles.md
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
- Role: a named bundle of responsibilities (editor, admin, member)
|
||||||
|
|
||||||
|
- Group: a scope or context (org, team, project, publication)
|
||||||
|
|
||||||
|
- Permission / Capability (capability preferred in code): a boolean fact about
|
||||||
|
allowed behavior
|
||||||
|
|
||||||
|
|
||||||
|
## tips
|
||||||
|
|
||||||
|
- In the database, capabilities are boolean values. Their names should be
|
||||||
|
verb-subject. Don't include `can` and definitely do not include `cannot`.
|
||||||
|
|
||||||
|
✔️ `edit_post`
|
||||||
|
❌ `cannot_remove_comment`
|
||||||
|
|
||||||
|
- The capabilities table is deliberately flat. If you need to group them, use
|
||||||
|
`.` as a delimiter and sort and filter accordingly in queries and in your
|
||||||
|
UI.
|
||||||
|
✔️ `blog.edit_post`
|
||||||
|
✔️ `blog.moderate_comment`
|
||||||
|
or
|
||||||
|
✔️ `blog.post.edit`
|
||||||
|
✔️ `blog.post.delete`
|
||||||
|
✔️ `blog.comment.moderate`
|
||||||
|
✔️ `blog.comment.edit`
|
||||||
|
are all fine.
|
||||||
17
docs/index.md
Normal file
17
docs/index.md
Normal file
@@ -0,0 +1,17 @@
|
|||||||
|
misc notes for now. of course this needs to be written up for real.
|
||||||
|
|
||||||
|
|
||||||
|
## execution context
|
||||||
|
|
||||||
|
The execution context represents facts such as the runtime directory, the
|
||||||
|
operating system, hardware, and filesystem layout, distinct from environment
|
||||||
|
variables or request-scoped context.
|
||||||
|
|
||||||
|
## philosophy
|
||||||
|
|
||||||
|
- TODO-DESIGN.md
|
||||||
|
- concentric-circles.md
|
||||||
|
- nomenclature.md
|
||||||
|
- mutability.md
|
||||||
|
- commands.md
|
||||||
|
- groups-and-roles.md
|
||||||
34
docs/migrations-and-seeders-and-database-table-ownership.md
Normal file
34
docs/migrations-and-seeders-and-database-table-ownership.md
Normal file
@@ -0,0 +1,34 @@
|
|||||||
|
Some database tables are owned by diachron and some are owned by the
|
||||||
|
application.
|
||||||
|
|
||||||
|
This also applies to seeders: some are owned by diachron and some by the
|
||||||
|
application.
|
||||||
|
|
||||||
|
The database's structure is managed by migrations written in SQL.
|
||||||
|
|
||||||
|
Each migration gets its own file. These files' names should match
|
||||||
|
`yyyy-mm-dd_ss-description.sql`, eg `2026-01-01_01-users.sql`.
|
||||||
|
|
||||||
|
Files are sorted lexicographically by name and applied in order.
|
||||||
|
|
||||||
|
Note: in the future we may relax or modify the restriction on migration file
|
||||||
|
names, but they'll continue to be applied in lexicographical order.
|
||||||
|
|
||||||
|
## framework and application migrations
|
||||||
|
|
||||||
|
Migrations owned by the framework are kept in a separate directory from those
|
||||||
|
owned by applications. Pending framework migrations, if any, are applied
|
||||||
|
before pending application migrations, if any.
|
||||||
|
|
||||||
|
diachron will go to some lengths to ensure that framework migrations do not
|
||||||
|
break applications.
|
||||||
|
|
||||||
|
## no downward migrations
|
||||||
|
|
||||||
|
diachron does not provide them. "The only way out is through."
|
||||||
|
|
||||||
|
When developing locally, you can use the command `develop reset-db`. **NEVER
|
||||||
|
USE THIS IN PRODUCTION!** Always be sure that you can "get back to where you
|
||||||
|
were". Being careful when creating migrations and seeders can help, but
|
||||||
|
dumping and restoring known-good copies of the database can also take you a
|
||||||
|
long way.
|
||||||
1
docs/mutability.md
Normal file
1
docs/mutability.md
Normal file
@@ -0,0 +1 @@
|
|||||||
|
Describe and define what is expected to be mutable and what is not.
|
||||||
@@ -2,3 +2,14 @@ We use `Call` and `Result` for our own types that wrap `Request` and
|
|||||||
`Response`.
|
`Response`.
|
||||||
|
|
||||||
This hopefully will make things less confusing and avoid problems with shadowing.
|
This hopefully will make things less confusing and avoid problems with shadowing.
|
||||||
|
|
||||||
|
## meta
|
||||||
|
|
||||||
|
- We use _algorithmic complexity_ for performance discussions, when
|
||||||
|
things like Big-O come up, etc
|
||||||
|
|
||||||
|
- We use _conceptual complexity_ for design and architecture
|
||||||
|
|
||||||
|
- We use _cognitive load_ when talking about developer experience
|
||||||
|
|
||||||
|
- We use _operational burden_ when talking about production reality
|
||||||
|
|||||||
@@ -1 +1,219 @@
|
|||||||
.
|
# Framework vs Application Ownership
|
||||||
|
|
||||||
|
This document defines **ownership boundaries** between the framework and application code. These boundaries are intentional and non-negotiable: they exist to preserve upgradeability, predictability, and developer sanity under stress.
|
||||||
|
|
||||||
|
Ownership answers a simple question:
|
||||||
|
|
||||||
|
> **Who is allowed to change this, and under what rules?**
|
||||||
|
|
||||||
|
The framework draws a hard line between *framework‑owned* and *application‑owned* concerns, while still encouraging extension through explicit, visible mechanisms.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Principle
|
||||||
|
|
||||||
|
The framework is not a library of suggestions. It is a **runtime with invariants**.
|
||||||
|
|
||||||
|
Application code:
|
||||||
|
|
||||||
|
* **uses** the framework
|
||||||
|
* **extends** it through defined seams
|
||||||
|
* **never mutates or overrides its invariants**
|
||||||
|
|
||||||
|
Framework code:
|
||||||
|
|
||||||
|
* guarantees stable behavior
|
||||||
|
* owns critical lifecycle and security concerns
|
||||||
|
* must remain internally consistent across versions
|
||||||
|
|
||||||
|
Breaking this boundary creates systems that work *until they don’t*, usually during upgrades or emergencies.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Database Ownership
|
||||||
|
|
||||||
|
### Framework‑Owned Tables
|
||||||
|
|
||||||
|
Certain database tables are **owned and managed exclusively by the framework**.
|
||||||
|
|
||||||
|
Examples (illustrative, not exhaustive):
|
||||||
|
|
||||||
|
* authentication primitives
|
||||||
|
* session or token state
|
||||||
|
* internal capability/permission metadata
|
||||||
|
* migration bookkeeping
|
||||||
|
* framework feature flags or invariants
|
||||||
|
|
||||||
|
#### Rules
|
||||||
|
|
||||||
|
Application code **must not**:
|
||||||
|
|
||||||
|
* modify schema
|
||||||
|
* add columns
|
||||||
|
* delete rows
|
||||||
|
* update rows directly
|
||||||
|
* rely on undocumented columns or behaviors
|
||||||
|
|
||||||
|
Application code **may**:
|
||||||
|
|
||||||
|
* read via documented framework APIs
|
||||||
|
* reference stable identifiers explicitly exposed by the framework
|
||||||
|
|
||||||
|
Think of these tables as **private internal state** — even though they live in your database.
|
||||||
|
|
||||||
|
> If the framework needs you to interact with this data, it will expose an API for it.
|
||||||
|
|
||||||
|
#### Rationale
|
||||||
|
|
||||||
|
These tables:
|
||||||
|
|
||||||
|
* encode security or correctness invariants
|
||||||
|
* may change structure across framework versions
|
||||||
|
* must remain globally coherent
|
||||||
|
|
||||||
|
Treating them as app‑owned data tightly couples your app to framework internals and blocks safe upgrades.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Application‑Owned Tables
|
||||||
|
|
||||||
|
All domain data belongs to the application.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
* users (as domain actors, not auth primitives)
|
||||||
|
* posts, orders, comments, invoices
|
||||||
|
* business‑specific joins and projections
|
||||||
|
* denormalized or performance‑oriented tables
|
||||||
|
|
||||||
|
#### Rules
|
||||||
|
|
||||||
|
Application code:
|
||||||
|
|
||||||
|
* owns schema design
|
||||||
|
* owns migrations
|
||||||
|
* owns constraints and indexes
|
||||||
|
* may evolve these tables freely
|
||||||
|
|
||||||
|
The framework:
|
||||||
|
|
||||||
|
* never mutates application tables implicitly
|
||||||
|
* interacts only through explicit queries or contracts
|
||||||
|
|
||||||
|
#### Integration Pattern
|
||||||
|
|
||||||
|
Where framework concepts must relate to app data:
|
||||||
|
|
||||||
|
* use **foreign keys to framework‑exposed identifiers**, or
|
||||||
|
* introduce **explicit join tables** owned by the application
|
||||||
|
|
||||||
|
No hidden coupling, no magic backfills.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code Ownership
|
||||||
|
|
||||||
|
### Framework‑Owned Code
|
||||||
|
|
||||||
|
Some classes, constants, and modules are **framework‑owned**.
|
||||||
|
|
||||||
|
These include:
|
||||||
|
|
||||||
|
* core request/response abstractions
|
||||||
|
* auth and user primitives
|
||||||
|
* capability/permission evaluation logic
|
||||||
|
* lifecycle hooks
|
||||||
|
* low‑level utilities relied on by the framework itself
|
||||||
|
|
||||||
|
#### Rules
|
||||||
|
|
||||||
|
Application code **must not**:
|
||||||
|
|
||||||
|
* modify framework source
|
||||||
|
* monkey‑patch or override internals
|
||||||
|
* rely on undocumented behavior
|
||||||
|
* change constant values or internal defaults
|
||||||
|
|
||||||
|
Framework code is treated as **read‑only** from the app’s perspective.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Extension Is Encouraged (But Explicit)
|
||||||
|
|
||||||
|
Ownership does **not** mean rigidity.
|
||||||
|
|
||||||
|
The framework is designed to be extended via **intentional seams**, such as:
|
||||||
|
|
||||||
|
* subclassing
|
||||||
|
* composition
|
||||||
|
* adapters
|
||||||
|
* delegation
|
||||||
|
* configuration objects
|
||||||
|
* explicit registration APIs
|
||||||
|
|
||||||
|
#### Preferred Patterns
|
||||||
|
|
||||||
|
* **Subclass when behavior is stable and conceptual**
|
||||||
|
* **Compose when behavior is contextual or optional**
|
||||||
|
* **Delegate when authority should remain with the framework**
|
||||||
|
|
||||||
|
What matters is that extension is:
|
||||||
|
|
||||||
|
* visible in code
|
||||||
|
* locally understandable
|
||||||
|
* reversible
|
||||||
|
|
||||||
|
No spooky action at a distance.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What the App Owns Completely
|
||||||
|
|
||||||
|
The application fully owns:
|
||||||
|
|
||||||
|
* domain models and data shapes
|
||||||
|
* SQL queries and result parsing
|
||||||
|
* business rules
|
||||||
|
* authorization policy *inputs* (not the engine)
|
||||||
|
* rendering decisions
|
||||||
|
* feature flags specific to the app
|
||||||
|
* performance trade‑offs
|
||||||
|
|
||||||
|
The framework does not attempt to infer intent from your domain.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What the Framework Guarantees
|
||||||
|
|
||||||
|
In return for respecting ownership boundaries, the framework guarantees:
|
||||||
|
|
||||||
|
* stable semantics across versions
|
||||||
|
* forward‑only migrations for its own tables
|
||||||
|
* explicit deprecations
|
||||||
|
* no silent behavior changes
|
||||||
|
* identical runtime behavior in dev and prod
|
||||||
|
|
||||||
|
The framework may evolve internally — **but never by reaching into your app’s data or code**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## A Useful Mental Model
|
||||||
|
|
||||||
|
* Framework‑owned things are **constitutional law**
|
||||||
|
* Application‑owned things are **legislation**
|
||||||
|
|
||||||
|
You can write any laws you want — but you don’t amend the constitution inline.
|
||||||
|
|
||||||
|
If you need a new power, the framework should expose it deliberately.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
* Ownership is about **who is allowed to change what**
|
||||||
|
* Framework‑owned tables and code are read‑only to the app
|
||||||
|
* Application‑owned tables and code are sovereign
|
||||||
|
* Extension is encouraged, mutation is not
|
||||||
|
* Explicit seams beat clever hacks
|
||||||
|
|
||||||
|
Respecting these boundaries keeps systems boring — and boring systems survive stress.
|
||||||
|
|||||||
@@ -0,0 +1,17 @@
|
|||||||
|
-- 0003_user_credentials.sql
|
||||||
|
-- Create user_credentials table for password storage (extensible for other auth methods)
|
||||||
|
|
||||||
|
CREATE TABLE user_credentials (
|
||||||
|
id UUID PRIMARY KEY,
|
||||||
|
user_id UUID NOT NULL REFERENCES users(id),
|
||||||
|
credential_type TEXT NOT NULL DEFAULT 'password',
|
||||||
|
password_hash TEXT,
|
||||||
|
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Each user can have at most one credential per type
|
||||||
|
CREATE UNIQUE INDEX user_credentials_user_type_idx ON user_credentials (user_id, credential_type);
|
||||||
|
|
||||||
|
-- Index for user lookups
|
||||||
|
CREATE INDEX user_credentials_user_id_idx ON user_credentials (user_id);
|
||||||
26
framework/platform
Normal file
26
framework/platform
Normal file
@@ -0,0 +1,26 @@
|
|||||||
|
# shellcheck shell=bash
|
||||||
|
|
||||||
|
# Detect platform (OS and architecture)
|
||||||
|
|
||||||
|
os=$(uname -s | tr '[:upper:]' '[:lower:]')
|
||||||
|
arch=$(uname -m)
|
||||||
|
|
||||||
|
case "$os" in
|
||||||
|
linux) platform_os=linux ;;
|
||||||
|
darwin) platform_os=darwin ;;
|
||||||
|
*) echo "Unsupported OS: $os" >&2; exit 1 ;;
|
||||||
|
esac
|
||||||
|
|
||||||
|
case "$arch" in
|
||||||
|
x86_64) platform_arch=x86_64 ;;
|
||||||
|
*) echo "Unsupported architecture: $arch" >&2; exit 1 ;;
|
||||||
|
esac
|
||||||
|
|
||||||
|
platform="${platform_os}_${platform_arch}"
|
||||||
|
|
||||||
|
# Platform-specific checksum command
|
||||||
|
if [ "$platform_os" = "darwin" ]; then
|
||||||
|
sha256_check() { shasum -a 256 -c -; }
|
||||||
|
else
|
||||||
|
sha256_check() { sha256sum -c -; }
|
||||||
|
fi
|
||||||
@@ -7,6 +7,15 @@ project_root="$node_common_DIR/../.."
|
|||||||
# shellcheck source=../versions
|
# shellcheck source=../versions
|
||||||
source "$node_common_DIR"/../versions
|
source "$node_common_DIR"/../versions
|
||||||
|
|
||||||
|
# shellcheck source=../platform
|
||||||
|
source "$node_common_DIR"/../platform
|
||||||
|
|
||||||
|
# Get platform-specific node directory
|
||||||
|
nodejs_dirname_var="nodejs_dirname_${platform}"
|
||||||
|
nodejs_dirname="${!nodejs_dirname_var}"
|
||||||
|
nodejs_dist_dir="framework/binaries/$nodejs_dirname"
|
||||||
|
nodejs_bin_dir="$nodejs_dist_dir/bin"
|
||||||
|
|
||||||
nodejs_binary_dir="$project_root/$nodejs_bin_dir"
|
nodejs_binary_dir="$project_root/$nodejs_bin_dir"
|
||||||
|
|
||||||
# This might be too restrictive. Or not restrictive enough.
|
# This might be too restrictive. Or not restrictive enough.
|
||||||
|
|||||||
@@ -2,18 +2,25 @@
|
|||||||
|
|
||||||
# This file belongs to the framework. You are not expected to modify it.
|
# This file belongs to the framework. You are not expected to modify it.
|
||||||
|
|
||||||
|
nodejs_version=v24.12.0
|
||||||
|
|
||||||
# https://nodejs.org/dist
|
# https://nodejs.org/dist
|
||||||
nodejs_binary_linux_x86_64=https://nodejs.org/dist/v24.12.0/node-v24.12.0-linux-x64.tar.xz
|
nodejs_binary_linux_x86_64=https://nodejs.org/dist/v24.12.0/node-v24.12.0-linux-x64.tar.xz
|
||||||
nodejs_checksum_linux_x86_64=bdebee276e58d0ef5448f3d5ac12c67daa963dd5e0a9bb621a53d1cefbc852fd
|
nodejs_checksum_linux_x86_64=bdebee276e58d0ef5448f3d5ac12c67daa963dd5e0a9bb621a53d1cefbc852fd
|
||||||
nodejs_dist_dir=framework/binaries/node-v22.15.1-linux-x64
|
nodejs_dirname_linux_x86_64=node-v24.12.0-linux-x64
|
||||||
nodejs_bin_dir="$nodejs_dist_dir/bin"
|
|
||||||
|
nodejs_binary_darwin_x86_64=https://nodejs.org/dist/v24.12.0/node-v24.12.0-darwin-x64.tar.xz
|
||||||
|
nodejs_checksum_darwin_x86_64=1e4d54f706e0a3613d6415ffe2ccdfd4095d3483971dbbaa4ff909fac5fc211c
|
||||||
|
nodejs_dirname_darwin_x86_64=node-v24.12.0-darwin-x64
|
||||||
|
|
||||||
caddy_binary_linux_x86_64=fixme
|
caddy_binary_linux_x86_64=fixme
|
||||||
caddy_checksum_linux_x86_64=fixmetoo
|
caddy_checksum_linux_x86_64=fixmetoo
|
||||||
|
|
||||||
# https://github.com/pnpm/pnpm/releases
|
# https://github.com/pnpm/pnpm/releases
|
||||||
pnpm_binary_linux_x86_64=https://github.com/pnpm/pnpm/releases/download/v10.28.0/pnpm-linux-x64
|
pnpm_binary_linux_x86_64=https://github.com/pnpm/pnpm/releases/download/v10.28.0/pnpm-linux-x64
|
||||||
pnpm_checksum_linux_x86_64=sha256:348e863d17a62411a65f900e8d91395acabae9e9237653ccc3c36cb385965f28
|
pnpm_checksum_linux_x86_64=348e863d17a62411a65f900e8d91395acabae9e9237653ccc3c36cb385965f28
|
||||||
|
|
||||||
|
pnpm_binary_darwin_x86_64=https://github.com/pnpm/pnpm/releases/download/v10.28.0/pnpm-macos-x64
|
||||||
|
pnpm_checksum_darwin_x86_64=99431e91d721169c2050d5e46abefc6f0d23c49e635a5964dcb573d9fe89975a
|
||||||
|
|
||||||
golangci_lint=v2.7.2-alpine
|
golangci_lint=v2.7.2-alpine
|
||||||
39
sync.sh
39
sync.sh
@@ -9,6 +9,26 @@ DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|||||||
# shellcheck source=framework/versions
|
# shellcheck source=framework/versions
|
||||||
source "$DIR/framework/versions"
|
source "$DIR/framework/versions"
|
||||||
|
|
||||||
|
# shellcheck source=framework/platform
|
||||||
|
source "$DIR/framework/platform"
|
||||||
|
|
||||||
|
# Get platform-specific variables
|
||||||
|
nodejs_binary_var="nodejs_binary_${platform}"
|
||||||
|
nodejs_checksum_var="nodejs_checksum_${platform}"
|
||||||
|
nodejs_dirname_var="nodejs_dirname_${platform}"
|
||||||
|
nodejs_binary="${!nodejs_binary_var}"
|
||||||
|
nodejs_checksum="${!nodejs_checksum_var}"
|
||||||
|
nodejs_dirname="${!nodejs_dirname_var}"
|
||||||
|
|
||||||
|
pnpm_binary_var="pnpm_binary_${platform}"
|
||||||
|
pnpm_checksum_var="pnpm_checksum_${platform}"
|
||||||
|
pnpm_binary_url="${!pnpm_binary_var}"
|
||||||
|
pnpm_checksum="${!pnpm_checksum_var}"
|
||||||
|
|
||||||
|
# Set up paths for shims to use
|
||||||
|
nodejs_dist_dir="framework/binaries/$nodejs_dirname"
|
||||||
|
nodejs_bin_dir="$nodejs_dist_dir/bin"
|
||||||
|
|
||||||
# Ensure correct node version is installed
|
# Ensure correct node version is installed
|
||||||
node_installed_checksum_file="$DIR/framework/binaries/.node.checksum"
|
node_installed_checksum_file="$DIR/framework/binaries/.node.checksum"
|
||||||
node_installed_checksum=""
|
node_installed_checksum=""
|
||||||
@@ -16,19 +36,19 @@ if [ -f "$node_installed_checksum_file" ]; then
|
|||||||
node_installed_checksum=$(cat "$node_installed_checksum_file")
|
node_installed_checksum=$(cat "$node_installed_checksum_file")
|
||||||
fi
|
fi
|
||||||
|
|
||||||
if [ "$node_installed_checksum" != "$nodejs_checksum_linux_x86_64" ]; then
|
if [ "$node_installed_checksum" != "$nodejs_checksum" ]; then
|
||||||
echo "Downloading Node.js..."
|
echo "Downloading Node.js for $platform..."
|
||||||
node_archive="$DIR/framework/downloads/node.tar.xz"
|
node_archive="$DIR/framework/downloads/node.tar.xz"
|
||||||
curl -fsSL "$nodejs_binary_linux_x86_64" -o "$node_archive"
|
curl -fsSL "$nodejs_binary" -o "$node_archive"
|
||||||
|
|
||||||
echo "Verifying checksum..."
|
echo "Verifying checksum..."
|
||||||
echo "$nodejs_checksum_linux_x86_64 $node_archive" | sha256sum -c -
|
echo "$nodejs_checksum $node_archive" | sha256_check
|
||||||
|
|
||||||
echo "Extracting Node.js..."
|
echo "Extracting Node.js..."
|
||||||
tar -xf "$node_archive" -C "$DIR/framework/binaries"
|
tar -xf "$node_archive" -C "$DIR/framework/binaries"
|
||||||
rm "$node_archive"
|
rm "$node_archive"
|
||||||
|
|
||||||
echo "$nodejs_checksum_linux_x86_64" >"$node_installed_checksum_file"
|
echo "$nodejs_checksum" >"$node_installed_checksum_file"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
# Ensure correct pnpm version is installed
|
# Ensure correct pnpm version is installed
|
||||||
@@ -39,15 +59,12 @@ if [ -f "$pnpm_installed_checksum_file" ]; then
|
|||||||
pnpm_installed_checksum=$(cat "$pnpm_installed_checksum_file")
|
pnpm_installed_checksum=$(cat "$pnpm_installed_checksum_file")
|
||||||
fi
|
fi
|
||||||
|
|
||||||
# pnpm checksum includes "sha256:" prefix, strip it for sha256sum
|
|
||||||
pnpm_checksum="${pnpm_checksum_linux_x86_64#sha256:}"
|
|
||||||
|
|
||||||
if [ "$pnpm_installed_checksum" != "$pnpm_checksum" ]; then
|
if [ "$pnpm_installed_checksum" != "$pnpm_checksum" ]; then
|
||||||
echo "Downloading pnpm..."
|
echo "Downloading pnpm for $platform..."
|
||||||
curl -fsSL "$pnpm_binary_linux_x86_64" -o "$pnpm_binary"
|
curl -fsSL "$pnpm_binary_url" -o "$pnpm_binary"
|
||||||
|
|
||||||
echo "Verifying checksum..."
|
echo "Verifying checksum..."
|
||||||
echo "$pnpm_checksum $pnpm_binary" | sha256sum -c -
|
echo "$pnpm_checksum $pnpm_binary" | sha256_check
|
||||||
|
|
||||||
chmod +x "$pnpm_binary"
|
chmod +x "$pnpm_binary"
|
||||||
|
|
||||||
|
|||||||
@@ -8,6 +8,12 @@
|
|||||||
|
|
||||||
{{ email }}
|
{{ email }}
|
||||||
</p>
|
</p>
|
||||||
|
{% if showLogin %}
|
||||||
|
<a href="/login">login</a>
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
{% if showLogout %}
|
||||||
<a href="/logout">logout</a>
|
<a href="/logout">logout</a>
|
||||||
|
{% endif %}
|
||||||
</body>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|||||||
Reference in New Issue
Block a user