ARCHITECTURE.md

Architecture

This document describes the high-level architecture of Cella.

1. Only build what you are going to use yourself.
2. Stay humble and remain a template, not a framework. So prevent abstraction layers.
3. A single, opinionated stack: ie. Cella uses Drizzle ORM and will not make it replaceable with another ORM.
4. Modularity. As CellaJS will grow, we need to make sure you can scaffold only the modules that you need.
5. Open standards. Our long term vision is that each Cella - as in each cell - can speak fluently with other cells.

Backend

• NodeJS
• Hono
• Postgres
• Drizzle ORM
• Zod
• OpenAPI
• JSX Email
• Oslo

Frontend

• React
• Tanstack Router
• Tanstack Query
• Zustand
• Electric Sync

Frontend / UI

• React Data Grid
• Shadcn UI
• I18next
• Lucide icons

Build tools

• pnpm
• Vite
• Vite-PWA
• Biome
• Lefthook
• PGLite

File structure

.
├── backend
|   ├── .db                   Location of db when using pglite
|   ├── emails                Email templates with jsx-email
│   ├── drizzle               DB migrations
│   ├── seed                  Seed scripts
│   ├── src                   
│   │   ├── db                Connect, table schemas
│   │   ├── lib               3rd part libs & important helpers
│   │   ├── middlewares       Hono middlewares
│   │   ├── modules           Modular distribution of routes, schemas etc
│   │   ├── permissions       Setup of your authorization layer
│   │   └── utils             Generic functions
├── config                    Shared config: default, development, production
├── frontend                  Frontend SPA
│   ├── public                
│   ├── src                   
│   │   ├── hooks             Generic react hooks
│   │   ├── json              Static JSON
│   │   ├── lib               Library code and core helper functions
│   │   ├── modules           Modular distribution of components
│   │   ├── routes            Code-based routes
│   │   ├── store             Zustand data stores
│   │   ├── utils             Generic functions
├── info                      General info
├── locales                   Translations
└── tus                       TUS server

Data modeling

Entities can be split in four types:

• All entities (user, organization, attachments)
• PageEntity: Entity that can be searched for (user, organization)
• ContextEntity: Has memberships (organization)
• ProductEntity: Content related entities without membership (attachment)

The default cella setup has one example product entity - attachments - and one context: organizations.

API Design

An OpenAPI is built with zod-openapi. Please read the readme in this middleware before you get started.

Modularity

Both frontend and backend already have many modules in common, such as authentication, users and organizations. There are more frontend modules however, also for home, marketing, navigation. The benefit of modularity is twofold: better code (readability, portability etc) and to make receiving cella updates possible.

Zooming in on some of the frontend modules:

• common: a cella-predefined set of reusable react components and services
• ui: Full with shadcn UI components. They have some small tweaks however and it is to be expected you will customize them yourself further.
• attachments: product entity module that has support for offline, optimistic updates and realtime sync.

A similar situation can be found in the types folders of both frontend and backend. you have app-specific types in app.ts and predefined cella types in common.ts.

Security

Link to valuable resources:

• https://mvsp.dev/mvsp.en/