README
¶
arandu-io/framework
The Arandu framework.
About Arandu
Note: this repository holds the core of the framework. To build an application with it, run
aru new <name>, or start from arandu-io/arandu.
Arandu is a Go framework for SaaS, and it has one claim: the architecture is not a convention the team agrees to follow, it is a shape the compiler refuses to break.
- Authorization that cannot be skipped — every repository signature takes a
Grant, and aGrantcomes from a policy. Reaching the database without one does not compile - Data access scoped by tenant — the tenant is read from the
Grant, never from what the caller sent, so one customer cannot name another's rows - Typed views, compiled — templates become Go, and a typo in a field name is a build error at the line you wrote, not a blank space in production
- Routing — resources, named routes and URL generation over
net/http - Diagnosis as a feature — a console, a request timeline and an N+1 detector in the core, allocating nothing when it is off
- Background work — jobs, a scheduler that holds a lock per replica, and events written to an outbox in the same transaction as the row that caused them
One direct dependency: golang.org/x/crypto. CI refuses the second.
Learning Arandu
The API reference is generated from the doc comments and lives on pkg.go.dev. Every exported symbol carries one, and that is deliberate: it is the documentation that cannot drift from the code, because it sits in the same file.
The CLI documents itself. aru help lists every command, and each one explains
what it writes and what to do with it. aru doctor explains what it found and
what breaks, not which rule was violated.
A guide and a website do not exist yet, and that is a decision rather than a gap: a guide written against an API that still moves is work done twice, and the second time is worse — there is wrong documentation published. The site is the next phase, and it will be an Arandu application.
Contributing
See CONTRIBUTING.md. Before opening a pull request, the three commands at the top of that file have to pass, and CI runs exactly them.
Security Vulnerabilities
Please review our security policy on how to report a vulnerability. Never open a public issue for one.
License
Open-sourced software licensed under the MIT license.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package arandutest holds the helpers a test needs and an application must not use.
|
Package arandutest holds the helpers a test needs and an application must not use. |
|
Package config holds the typed application configuration.
|
Package config holds the typed application configuration. |
|
Package data defines the data access contract.
|
Package data defines the data access contract. |
|
Package events is domain events with an outbox.
|
Package events is domain events with an outbox. |
|
Package httpx is the routing layer.
|
Package httpx is the routing layer. |
|
middleware
Package middleware holds the mandatory request pipeline.
|
Package middleware holds the mandatory request pipeline. |
|
Package jobs is the queue contract: work that happens after the response.
|
Package jobs is the queue contract: work that happens after the response. |
|
Package kernel boots the application.
|
Package kernel boots the application. |
|
Package mail sends what an application has to say to somebody.
|
Package mail sends what an application has to say to somebody. |
|
modules
|
|
|
auth
Package auth is the first first-party module and the canonical reference: every module the CLI generates has exactly this shape.
|
Package auth is the first first-party module and the canonical reference: every module the CLI generates has exactly this shape. |
|
Package observability is the reason this framework exists.
|
Package observability is the reason this framework exists. |
|
errorpage
Package errorpage renders the development error page.
|
Package errorpage renders the development error page. |
|
Package scheduler runs the tasks modules declare.
|
Package scheduler runs the tasks modules declare. |
|
Package security holds the authorization primitives of the framework.
|
Package security holds the authorization primitives of the framework. |
|
Package storage is the file contract: what a tenant uploaded, and where it went.
|
Package storage is the file contract: what a tenant uploaded, and where it went. |
|
Package validation defines the validation contract.
|
Package validation defines the validation contract. |
|
Package view is the view layer: kyse for markup, HTMX for interaction, Alpine for ephemeral client state, Tailwind for style.
|
Package view is the view layer: kyse for markup, HTMX for interaction, Alpine for ephemeral client state, Tailwind for style. |