High-level architecture of the BISO Sites monorepo including system design, data flow, and key architectural decisions.

Architecture Overview

This document provides a high-level overview of the BISO Sites monorepo architecture, explaining how all the pieces fit together and why certain architectural decisions were made.

System Architecture

BISO SItes is built as a monorepo containing multiple applications that share common packages. The architecture follows these key principles:

Separation of Concerns - Clear boundaries between applications and packages
Code Reusability - Shared packages eliminate duplication
Type Safety - Full TypeScript coverage across all code
Framework Agnostic Packages - Packages don't depend on Next.js runtime
Scalability - Can add new apps and packages easily

High-Level Diagram

Layer Architecture

The system is organized into distinct layers:

Presentation Layer (Apps)

Responsibility: User interface and user interactions

Web App - Public-facing UI for end users
Admin App - Management interface for content creators
Docs App - Documentation for developers

Technologies:

Next.js 15 App Router
React 19
Server Components & Server Actions
next-intl for i18n

Business Logic Layer (Packages)

Responsibility: Reusable business logic and utilities

@repo/api - Appwrite API wrappers
@repo/payment - Payment processing logic
@repo/editor - Page builder configuration

Key Principle: Framework-agnostic, testable, pure TypeScript

Presentation Components Layer (@repo/ui)

Responsibility: Reusable UI components

shadcn/ui components
Custom composite components
Theme provider
Styling utilities

Technology: React + Tailwind CSS

Infrastructure Layer (Backend)

Responsibility: Data persistence, authentication, file storage

Appwrite - Primary backend
- Database (NoSQL/Document)
- Authentication & Authorization
- File Storage
- Real-time subscriptions
External Services
- Vipps MobilePay (payments)
- OpenAI API (AI features in admin)

Architectural Patterns

Monorepo Pattern

Why Monorepo?

✅ Benefits:

Share code between apps without publishing packages
Single version of dependencies across all apps
Atomic commits across multiple apps
Consistent tooling and configuration
Easy to refactor across boundaries

❌ Challenges:

Larger repository size
Need proper build orchestration (solved with Turborepo)

Implementation:

Turborepo for build orchestration
Bun workspaces for dependency management
Shared tsconfig and eslint configs

Dependency Injection Pattern

Used in the payment package to keep it framework-agnostic.

Before (❌ Tight Coupling):

// packages/payment/vipps.ts
import { createSessionClient } from '@repo/api/server'; // Next.js dependency!

export async function createCheckout(params) {
  const { db } = await createSessionClient(); // Importing Next.js runtime
  // ... logic
}

After (✅ Dependency Injection):

// packages/payment/vipps.ts
// No Next.js imports - framework agnostic!

export async function createCheckout(params, db) {
  // db is passed as parameter
  // ... logic
}

Benefits:

Package can be used in any Node.js environment
Easy to test (mock the db)
Clear dependencies
Follows SOLID principles

See Dependency Injection for full details.

Server-First Architecture

Leveraging Next.js App Router's server-first approach:

Server Components (Default):

Fast initial page load
SEO friendly
Direct database access
Reduced client bundle size

Client Components (When Needed):

Interactivity (onClick, useState, etc.)
Browser APIs
Third-party libraries that need window/document

Server Actions:

Type-safe mutations
No API routes needed for simple operations
Progressive enhancement

Internationalization (i18n)

Pattern: Route-based localization

// URL structure
/en/about  -> English
/no/about  -> Norwegian

// Message files
messages/
├── en/
│   └── about.json
└── no/
    └── about.json

Benefits:

SEO friendly (different URLs per language)
Easy to add new languages
Type-safe translations with next-intl

Component Composition

UI components follow atomic design principles:

// Atoms
<Button />
<Input />

// Molecules  
<SearchBar />
<NavItem />

// Organisms
<Navigation />
<HeroSection />

// Templates (Layouts)
<DashboardLayout />

// Pages
<HomePage />