Building a Solution
A solution is a site that is also an app. Visitors read its public pages. Its members sign in to pages of their own — a learner's courses, a client's orders — and the people who run it work in an admin area made for what it does. All of it is built in one foundation, on the site's own backend: the backend service of Uniweb hosting.
You don't write the server. The backend is a service: accounts, sign-in, roles, each member's entries and who may read them, a store, an inbox, and integrations with other systems are already there. Your foundation declares what the app needs and draws every screen people use.
Audience: developers, and the agents working for them, building a site where people sign in. Sites with Accounts covers the
backendservice itself; this page puts the parts of a solution together.
The four parts
| part | who uses it | what it is |
|---|---|---|
| Public pages | visitors, signed in or not | section types an author composes, as on any site; records the site shows; forms a visitor fills with no account |
| The members' area | each kind of member: a learner, a client, an attendee | pages of section types no author composes, reading and writing the member's own entries through @uniweb/api |
| Your admin area | the people who run the solution: its instructors, its sales team, its staff | your section types too, branded, in the solution's own words |
| The admin app | the site's owner | the backend's own administration, the same for every site |
Your admin area is the solution's; the admin app is every site's. Build an admin area that speaks your solution's language and does its work: a course's roster and grading, a dealership's inventory and requests. Leave to the admin app what every site has, done the same way for all of them: the site's payment account, the teams and who is in them, roles, an integration's address and keys, the store's offerings and coupons. A member the admin app admits reaches it from your site through its Admin link (adminHref from useSession()).
The path, step by step
1. Name the roles
Start from the people, not the pages. Who comes to the site, and what does each one do? A course platform has visitors, learners, instructors and the owner; a dealership has shoppers, sales and service staff. List the pages each role needs, the ones it grows into included: a member's profile and settings, and the page a mailed link lands on.
2. Model the types, with their rules
Each kind of entry is a data schema (Data Schemas): a course, a lesson, a submission. The backend applies a schema's rules on every write, whatever the screen does, so put the rules there:
append_onlyon a section that is added to and never edited, such as attendance;readable_with: editon a reference, so the people who edit the course read every submission to it;sold_with: trueon a reference, so whoever bought the course reads its lessons;grantable: falseon a type whose entries are never shared one by one;visitor_fills: trueon the fields a visitor with no account may fill.
3. Write the blueprint
blueprint.yml, beside site.yml, says how the site's backend starts (Blueprint): who may sign up, the teams it founds, who adds entries of each type, who reads or edits all of them, what visitors who aren't signed in may read, and the integrations it starts with.
Every type starts closed: only the account that runs the site adds entries of it. Open the types that need opening — the ones members create, and the ones a team keeps — and leave closed what only the owner writes. The blueprint applies once, when the backend starts; after that, the owner changes these settings in the admin app.
4. Build the members' area and your admin area
Both are section types that read and write through @uniweb/api:
- The session:
useSession, sign-in and sign-up (useSignIn,useSignUp), the links the backend mails (useMailedLink). - Entries:
useRecordslists them,useEntityreads one, anduseEntityWriterwrites it. - Sharing:
useAccessgives a personread,editoradminon an entry, such as an instructor enrolling a student.useInvitationsanswers an invitation, anduseUnitssays where a new entry lands. - Acting for the solution: an administrator acts through their role only after confirming it is them (
useElevation). Draw your admin area's controls from what each record says the viewer may do, since the backend decides.
Ask whether the site has the service before drawing any of it: isBackendEnabled() from @uniweb/kit. The same foundation then also serves a site without the service, and what needs the backend draws nothing there.
5. If it sells
The owner sets what the site sells in the admin app, and connects their own Stripe account there. Your section types draw the store and its checkout:
useStorereads the store's offerings, and whether the viewer owns each. Itscheckoutsends the buyer to the payment page, or takes a free offering at once.offeringStatesays what a Buy button draws from that one read.useEntitlementslists what a member holds, for a "My courses" page, anduseHolderslists who holds a record, for an instructor's roster.
A purchase gives the buyer read access to what an offering sells, and, through it, to what its sold_with references point to. The @uniweb/api README has the details, under Selling.
6. Tell people what concerns them
The backend writes to each member's inbox: an entry someone shared with them, an invitation. useNotifications reads it — a badge with the unread count, and the rows when the member opens them.
7. Connect other systems
An integration moves entries of a type to or from another system, through one of your foundation's mappings: a catalog feed out, a lead in (Blueprint § Integrations). Small logic, such as grading a quiz against an answer key a learner must never see, can be a compute function your foundation ships, which the platform runs.
8. Work on your machine
$devBackend in site.yml answers the backend service under uniweb dev with a local mock (Sites with Accounts § Building before the server exists). Hand it your blueprint, and it applies it: every type closed until the blueprint opens it, each entry its owner's, append_only held. Seed it with accounts for each role, the entries they start with, a store and an inbox, and walk each role's pages. The mock is for working with no backend at hand. The site's own backend, once it has one, is where you check that each role can do what it must.
9. Publish, and hand over
uniweb publish takes the site live on Uniweb hosting, and the backend service gives it a backend of its own, started from its blueprint. Uniweb hosting and the backend service are paid. The first time, the browser opens to the page where the site's owner pays.
Then the owner sets up what is theirs, in the admin app: their payment account, the people in each team, roles, and an integration's address. None of it belongs in your files.
A worked example
uniweb create my-event --template conferenceAn event site that is also an app: a programme the organiser keeps, which every member reads, and the attendance each attendee keeps for themselves. It comes with services.backend, $devBackend, a seeded mock and a blueprint already wired.
See also
- Sites with Accounts: the
backendservice, the mock, and the habits a component needs - Blueprint: how a site's backend starts
- Compute Functions: small logic the platform runs for your foundation
- Data Schemas: the types, and the rules the backend holds
@uniweb/api: the client, in fulluniweb guide backend: the same, written for the agent building it