Architecture Overview
High-level architecture of the BISO Sites monorepo — system design, layers, and where to read next.
Architecture Overview
This page is the map of the BISO Sites monorepo: how apps and packages fit together, which layers exist, and which patterns we use. Deep dives live on dedicated pages linked below.
System Architecture
BISO Sites is built as a monorepo with shared packages consumed by multiple Next.js apps. Principles:
- Separation of concerns — Clear boundaries between applications and packages
- Code reuse — Shared packages avoid duplication
- Type safety — TypeScript across apps and packages
- Framework-agnostic packages — Core logic does not depend on the Next.js runtime
- Scalability — New apps or packages can be added without rewriting the whole stack
High-Level Diagram
Layer Architecture
Presentation layer (apps)
Responsibility: UI and user interactions.
- Web — Public site for visitors
- Admin — CMS and operations
- Docs — This documentation site
Stack: Next.js App Router, React 19, Server Components and Server Actions, next-intl where applicable.
Business logic layer (packages)
Responsibility: Reusable logic and integrations.
- @repo/api — Appwrite clients and helpers
- @repo/payment — Payments (e.g. Vipps)
- @repo/editor — Puck-based page builder
Principle: Prefer pure TypeScript cores that are easy to test and reuse.
Presentation components (@repo/ui)
Responsibility: Shared UI (shadcn/ui–style components, patterns, theme).
Infrastructure (backend and external APIs)
Responsibility: Persistence, auth, storage, and third-party services (Appwrite, Vipps, OpenAI for admin features).
Architectural Patterns
1. Monorepo
Turborepo orchestrates builds; Bun workspaces manage dependencies; shared ESLint and TypeScript configs keep tooling consistent. Trade-offs and tooling choices are summarized in Design decisions.
2. Dependency injection
Packages such as @repo/payment accept dependencies (for example a database client) as parameters so core logic stays free of Next.js imports. Full rationale and examples: Dependency injection.
3. Server-first UI
Default to Server Components; use Client Components for interactivity; use Server Actions for mutations where appropriate. End-to-end request paths (reads, writes, webhooks, caching) are documented in Data flow.
4. Internationalization
Route-based locales (for example /en/..., /no/...) with message files per locale and next-intl on the web app.
5. Component composition
UI is composed from small primitives up to layouts and pages (atoms → molecules → organisms → templates), primarily via @repo/ui.
Where to read next
| Topic | Page |
|---|---|
| Rationale for Turborepo, Bun, Appwrite, Next.js, DI | Design decisions |
| Security, performance, scalability, build pipeline | Quality and operations |
| Reads, writes, auth, payments, caching | Data flow |
| Apps at a glance (ports, roles, links to guides) | Applications in the monorepo |
| Package roles and dependency graph | Packages in the monorepo |
For day-to-day work on a specific app, start from Applications and the Packages reference sections — they are the canonical place for feature-level detail.