---
# System prepended metadata

title: Architecture Spec draft

---

# Jan's System architecture - peer review

This is the architecture draft for the `Jan` app, not `Nitro`.
Goals:
- Attract new developers -> Jan needs to be modular and extensible.
- Modular means dev can easily break apart Jan and replace part of it with their own part
- Extensible means dev can easily utilize parts Jan have provided, and build functionality on top of it. 
- Simplicity, Simplicity, Simplicity
- 

Concerns: 
- Module and extension lifecycles - loaded, enabled
- Distinguishing server/client/core/pluggable modules
- Compare server/client vs main/renderer. 
- Cloud native? 
- Sandboxing
-- Extension Devs always assume a flat-file system, with a defined JSON
-- Backend service can implement it using a DB (if they want)
-- Backend service can implement using a sandboxed filesystem too
- 
- 

## Overall architecture
The 2 abstractions that are essential to Jan are `Modules` and `Extensions`
- `Modules` lies at lower/system level. Think of it as OS kernel modules, that provides abstractions to things that are seen as basic, familiar to developer users like the file system, device system, databases, inference engines etc. 
- `Extensions` represents higher-level application that the developers want to bring to their end-users, crafting it by using the modules' interfaces

<!-- Note: Extensions map to "Use Cases" in the popular "The Clean Architecture"
![image](https://hackmd.io/_uploads/HytULbp4a.png) -->
In this sense the Jan application is a just a set of built-in modules plus a set of pluggable modules

![image](https://hackmd.io/_uploads/BJtw9ZpV6.png)

## Modules
![image](https://hackmd.io/_uploads/Sk16oZ6Na.png)
Some examples of modules are:
- File-system which provides hierarchical data structure with permission control like chmod, chown
- Data-store which provides interfaces mirroring popular DB system so that dev easily migrate their existing code that operates on DBs
- AuthN/AuthZ
- Inference provides universal access to LLM models, remote or local.

Modules are generally independent of each other, as there are no dependency management for those. For example:
- The `Data store`  module cannot re-use the `File-system` module for storing the database, but will have to implement its own file-system for its own sake.
- If we want to build a custom `File system` module that proxy to an external service (e.g: AWS S3) that requires authentication, it will have to implement its own version even if such code exist in the `AuthN/AuthZ` module.

Module and can only be configured deploy-time and cannot be hot-swapped at run-time. Its lifecycle binds with Jan application.
 
Q: Should `Modules` runs on its own process?


## Extensions
![image](https://hackmd.io/_uploads/B1hPmGT4p.png)


An extension consist of 2 main part: 
- `Manifest.json` file which tells the `Extension management` module about the extensions:
    - Dependency on other modules
    - How the client and server communicate - protocol, port, message descriptions, etc.
    - Misc information: name, description, author, etc.
- A pair of `client/server` code that will aligns on the interfaces, using a communication protocol specified in the `Manifest.json` file

Extensions depends on a set of modules and its lifecycle is either `installed` or `enabled`.

## Examples
Below are some examples - reflecting the architecture spec on what we have built so far
### Desktop App
Our Jan desktop app can be seen as a Server and Client, either wrapped inside Electron, or separated over different networks: 
![image](https://hackmd.io/_uploads/rk-SDfp4T.png)


### Model extension
On the client side, the `Model extension` code will have to register new pages to the `Core`, e.g:  `Local model`, `Model catalog`, `Model recommendation`

![image](https://hackmd.io/_uploads/ryosuWiNp.png)

- Local model showing alr downloaded models + let the user choose to start/stop them. In order to do so, file-system and inference modules need to be utilized to load the model file to the inference engine (Nitro)
- Model catalog needs the help of the downloader module for reaching external model sources 


### Chat extension
Chat extension enables users to interact with LLMs, and can use chat applications like Telgram/Slack/Discord as a text channel.

![image](https://hackmd.io/_uploads/Byj07g0VT.png)


The chat client extension will encode all users' interactions like stickers, picture sharing, file sharing to a format which is aligned with the server extension. 

The server extension will decode the information and use the inference engine in its own creative way and returns the chat output in a format aligned with the client. 
