DEV Community: Max

Building a Generative Image Bot with OpenAI, Telegram, FastAPI and Deta Space

Max — Fri, 31 Mar 2023 08:53:20 +0000

You may have seen some of the amazing images generated by new AI services, like Midjourney and Open AI's DALL·E 2.

Want to get in on the action? In this step-by-step guide, we'll build a personal Telegram bot that will let you use DALL·E 2 from your phone.

When we're done, you'll have a fully functional bot capable of creating unique images from your own input. Your server will run and your images will be stored in your own personal cloud on Deta Space, where you can easily access and use them in other projects.

Let's get going.

Prerequisites

Before starting, out you will need the following, at a minimum:

A Telegram Account
An OpenAI Account
A Deta Space Account (make sure to enable Developer Mode when signing up)

Optional:

Additionally, you’ll want Python on your local machine, if you want to develop locally

Architecture

Architecturally, the bot is pretty simple:

Interface: A personal Telegram bot will serve as your primary user interface, where you’ll send prompts and receive images.
Generative Image Service: DALL·E 2 (OpenAI’s service for turning language into images) will turn the prompts into images.
Server + State: In between, you’ll run a FastAPI server on Deta Space to bridge Telegram and DALL·E 2. This server will save every image in a personal file store on Deta Drive.

Step 1: Creating Your Bot and Getting the Keys

The first step is to create the bot in Telegram and get the required keys from both Telegram and Open AI.

Telegram Bot Token

Search for BotFather in Telegram and start a conversation with it, by clicking the START button.

Type /newbot, and follow the prompts to set up a new bot with a name and username for your bot. BotFather will give you the bot token that you will use to authenticate your bot. Save this token somewhere safe; you will need it later.

⚠️ Keep your token secure, it can be used anyone to control your bot.

Open AI API Key

Next, create an OpenAI account and get an OpenAI API key. This key will let your assistant generate an image with DALL·E 2.

Step 2: Writing Your Bot’s Code

The server we'll write is fairly simple and will do two core things:

Use incoming messages from Telegram to generate images with DALL·E 2.
Save the generated images to your personal cloud and send them back to Telegram.

The complete code is in this repository, and the core logic lives in the main.py file. The external Python libraries required are listed in the requirements.txt file.

Setup a Webhook with Telegram

Before Telegram can send our server a webhook on every message, it needs to know about our server. The /set_webhook route, when triggered, will configure the connection with Telegram. Once configured, Telegram will send events to our server's /open route.

The code assumes we’ve set the Bot Key as an environment variable in Deta Space (TELEGRAM). It also assumes it's running on Deta Space, as it grabs the server url from the Space environment. But we’ll deploy the code to Deta Space and set the environment variables later.

Let’s move onto the main logic of our bot.

Process Messages from Telegram

The first step for the core logic of the bot is to process an incoming message from Telegram as a prompt for the DALL·E 2 API. The /open route in our server will handle this.

One thing to be aware of is that anyone can message our bot. But we don’t want them to be able to generate and receive images. So we’ll create a simple system to control who has access by checking the chat_id Telegram sends. Later on, we'll create an admin page that will let us add chat_ids to an authorized list.

Here's the relevant code that parses the incoming request and checks the chat_id against a list of authorized chat_ids:



from deta import Base, Drive
# ... other code
CONFIG = Base("config")
# ... other code

@app.post("/open")
async def http_handler(request: Request):
    incoming_data = await request.json()

    if "message" not in incoming_data:
        print(incoming_data)
        return send_error(None, "Unknown error, lol, handling coming soon")

    prompt = incoming_data["message"]["text"]
    chat_id = incoming_data["message"]["chat"]["id"]

    # ... other functionality
    authorized_chat_ids = CONFIG.get("chat_ids")

    # ... other functionality
    if authorized_chat_ids is None or chat_id not in authorized_chat_ids.get("value"): 
        payload = {"text": "You're not authorized!", "chat_id": chat_id}
        message_url = f"{BOT_URL}/sendMessage"
        requests.post(message_url, json=payload).json()
        return

One note: we assume that we've stored a list of authorized chat_ids in a Deta Base, Deta's database service. After we validate the chat_id, we can grab the message and use it as a prompt for DALL·E 2 using a function get_image_from_prompt.

Generate Images with DALL-E 2

get_image_from_prompt is the function that sends the prompt to DALL·E 2, via the openai Python library. It'll get an image as a response.




OPEN_AI_KEY = os.getenv("OPEN_AI")

openai.api_key = OPEN_AI_KEY

def get_image_from_prompt(prompt):
    try:
        response = openai.Image.create(
            prompt=prompt,
            n=1,
            size="512x512",
            response_format="b64_json",
        )

        if "error" not in response:
            return {
                "b64img": response["data"][0]["b64_json"],  # type: ignore
                "created": response["created"],  # type: ignore
            }
        return {"error": response["error"]["message"]}  # type: ignore
    except Exception as e:
        return {"error": str(e)}  # type: ignore

Using the defaults we’ve set, we’ll get a 512x512 image response as base-64 encoded JSON. This code block assumes our server has the Open AI key from earlier, stored in its environment as OPEN_AI_KEY, but we’ll set that later.

Now that we've got an image, we can save it and send it back to Telegram!

Save the images and send them back to Telegram

To save our image, we'll use Deta Drive, which will let us create a file store in our personal cloud. We can then send it the image back to our Telegram chat.

Both are done in the rest of the /open handler function from earlier, using a helper function save_and_send_img:



from deta import Base, Drive
# ... other code

PHOTOS = Drive("generations") # instantiate the Deta Drive
# ... other code

def save_and_send_img(b64img, chat_id, prompt, timestamp):
    image_data = base64.b64decode(b64img)
    filename = f"{timestamp} - {prompt}.png"
    PHOTOS.put(filename, image_data)
    photo_payload = {"photo": image_data}
    message_url = f"{BOT_URL}/sendPhoto?chat_id={chat_id}&caption={prompt}"
    requests.post(message_url, files=photo_payload).json()
    return {"chat_id": chat_id, "caption": prompt}

# ... other code

@app.post("/open")
def http_handler(request: Request):
    # ... other code
    open_ai_resp = get_image_from_prompt(prompt)

    if "b64img" in open_ai_resp:
        return save_and_send_img(
            open_ai_resp["b64img"], chat_id, prompt, open_ai_resp["created"]
        )

    if "error" in open_ai_resp:
        return send_error(chat_id, open_ai_resp["error"])

    return send_error(chat_id, "Unknown error, lol, handling coming soon")

This function takes the base-64 encoded image and decodes it. Then it stores it to your Drive and sends it back to your Telegram bot.

Lastly, we'll talk about the management UI for your bot.

Creating a Management UI for your Bot

As the bot's owner, you'll want to know the bot's state, trigger the setup webhook with Telegram, and manage authorized chat_ids.

This is all done in a simple UI, declared in a single index.html file, with a bit of support from JS and CSS. This HTML file is served by the server in main.py via the /, /setup, and /authorize routes as a Jinja template.

Step 3: Running the Bot

Once you have written the code for your bot, you can deploy and run it out of your personal cloud in Deta Space.

Creating a Project in Deta Space

Before doing so, you’ll need to need to install and login to the Deta Space CLI. Then, ensure your local code has the server in your main.py file and dependencies in your requirements.txt file.

After you have the code, you can create your first Space Project. The CLI can bootstrap your project for Deta Space, if you haven't cloned the repository from GitHub.

In either case, you'll notice there is a Spacefile, which will tell Deta Space how to run your app. We'll want to ensure a few things about this Spacefile:

First, that the public_routes parameter is present, telling Deta Space to leave the /open route open to the public (so Telegram can send it events).
Second, to set two environment variables under the env parameter: TELEGRAM and OPEN_AI. We'll use these in our app to store the Telegram and Open AI keys, respectively.

The Spacefile also gives the app a name and sets an icon, among other things.

An example of a working Spacefile for our bot is here. But to make things easiest, it's recommended to clone the entire GitHub repository to bootstrap all the files.

Pushing Your Code and Setting Your Environment Variables

Once you’ve got your code ready and project created, you can push your local code to Deta Space with the Space CLI command space push. This will bundle your local code and deploy it as a usable app on Deta Space.

Once pushed, you’ll see a new icon in your Deta Space Canvas (the dashboard), which you'll see when you log in to Space. If you click the ..., then Settings, and then the Configuration tab, you’ll be able to set the environment variables.

Enter the Open AI API key and Telegram Bot Key from earlier and click Save.

Setting the Webhook & Chat ID

Now that you’ve added the environment variables, you can configure your assistant with the bot we’ve created in Telegram. Click your app’s icon from the Deta Space Canvas (dashboard) to visit the bot’s admin panel. (On Deta Space, you are authenticated, so this view is only accessible to you).

If you’ve saved the Configuration Variables from the last step, it should show you the button to setup your webhook. Click the Setup Webhook button to do so.

One final step we’ll have to do is add your own chat_id to the list of authorized users:

Add your bot in Telegram as a contact via its username.
Then talk to it with the command “/chatid” to get the ID of your chat from your bot.
Third, Visit the the admin UI again, click the authorize button and then the add new chat id button.
Finally, enter the ID into the input field and click submit.

You are now ready to generate images!

Running Your Assistant

Send your bot a message on Telegram, containing any prompt. Your bot should respond with the resulting image!

Accessing Your Photos

All the images you generate will be stored on your personal cloud in a Drive. You can view and download the photos, as well as program against them using the Deta Drive SDK. Click on the View Data option from the ... menu of your app, and then click the Drive tab to see everything you've got.

Other Options for Running Your Bot

You can install the app built in this tutorial in your own personal cloud in one click here. No coding is necessary, you’ll just need to:

create a Telegram bot.
set the Open AI and Telegram bot keys.
visit the “/” route to configure everything before using the bot.

You can also run your assistant anywhere a uvicorn server will run, including locally for development. In the local case, you’ll need to use something like ngrok to tunnel your local host to an https url (and modify the DETA_SPACE_HOSTNAME variable in the code to grab the nrgok hostname).

Final Words

Congratulations — you’ve got an AI assistant running in that can be accessed from your phone. It'll operate and store everything in your own cloud.

One idea for you to play with is to expose the image-generating function as an API, which you can use from a number of other apps (check out the API Keys on Deta Space).

But have fun generating all sorts of images. In the next part of our series, we’ll be adding the ability to chat with our assistant, similar to ChatGPT — stay tuned!

Special thanks to Bighneswar Parida for assistance with code + words.

Persistent To Dos with Next.js + Deta Base in 7 minutes

Max — Wed, 11 Nov 2020 08:29:03 +0000

Next.js adds a lot on top of React; with support for api routes with serverless functions out of the box, Next let's you do traditional 'server side' tasks, like making authenticated requests to a database. If you deploy on Vercel, the pages/api directory will auto deploy as functions.

As we spoke about previously, traditional databases are not a great fit in the serverless model, where persistent connections don't mesh well with asynchronous, ephemeral, functions; Vercel suggests connection pooling as one way to mitigate these issues. Using a pure serverless database—where database requests do not rely on a persistent database connection—is another way around this issue.

This tutorial will guide you through creating a To Do app using Next.js and Deta Base, with deployments on Vercel. This app will be fundamentally different from a client side state model where To Do state is only stored in a React Component. In this app, the serverless functions will talk to Deta Base which will store the To Do state. This will provide To Dos a persistence that extends beyond component unmount and, as will be seen, Deta Base's GUI can be used to update To Do state, feeding back into our Next.js app.

This app uses the Create Next App starter, and the full source code is here.

Deploy instructions are here.

Design

The fundamental unit of our application will be a To Do, which will exist as a JSON object:

{
    "content": "Wake Up On Time", // string
    "isCompleted": false // boolean
}

These to dos will be stored in Deta Base and ultimately rendered by our Next.js app. To do so requires adding the deta dependency to your project using npm install deta or yarn add deta.

Additionally, our Next.js app needs to be able to generate and interact with this data. We can tie the four basic CRUD functions to two endpoints / serverless functions in Next.js

Create a new To Do: POST api/todos
Read all the To Dos: GET api/todos
Update a To Do (of id tid ): PUT api/todos/{tid}
Delete a To Do (of id tid ): DELETE api/todos/{tid}

The basic Next.js file structure for our application is as follows (modified from the Create Next App starter).

/pages
    index.js (our frontend logic)
    /api
            /todos
                index.js (function, will handle the GET & POST)
                [tid].js (function, will handle the PUT & DELETE)

Creating a To Do

To create a To Do, let's create an api call that will call POST api/todos based on some newContent stored in a React State Hook (this is tied to an input element in line 84):

export default function Home() {

  const [newContent, setNewContent] = useState('');

  ...


  const createToDo = async () => {
    const resp = await fetch('api/todos', 
      {
        method: 'post', 
        body: JSON.stringify({content: newText})
      }
    );
    // await getToDos(); To Be Implemented
  }

    ...
    return (
    ...
            <input className={styles.inpt} onChange={e => setNewContent(e.target.value)}></input>
    ...
    )

}

The function createToDo, when called, will pull the value of newContent from state in React and POST it to our endpoint, which we handle at pages/api/todos/index.js (link here):

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import { Deta } from 'deta';

const deta = Deta(process.env.DETA_PROJECT_KEY);

const base = deta.Base('todos');

export default async (req, res) => {
  let { body, method } = req;
  let respBody = {};

  if (method === 'GET') {

    // To Be Implemented

  } else if (method === 'POST') {

    body = JSON.parse(body);
    body.isCompleted = false;
    respBody = await base.put(body);
    res.statusCode = 201;

  }

  res.json(respBody);
}

In this handler, we access a project key that we get from Deta and store in a Vercel Environment Variable. This key allows us to talk to any Base in that Deta project, in this case a database we have called todos. Using the Deta SDK, we can take the content from the api call, add an isCompleted field, and use the put method to store our new to do in our database. A key will be automatically generated under which this item will be stored.

Reading To Dos

To read all our To Dos, let's create an api call that will call GET api/todos and store it in a React hook in the home component of pages/index.js .

Secondly, let's also use a React useEffect hook to call this function when our component mounts.

Third, let's create two lists from our to dos, that will give us the list of to dos by completion status, which we will display in different parts of our app (lines 89 and 106 of index.js).

This relies on us having a working ToDo component, which we will assume correctly displays content and completion status for now.

export default function Home() {

  const [newContent, setNewContent] = useState('');

  const [toDos, setToDos] = useState([]);

  const getToDos = async () => {
    const resp = await fetch('api/todos');
    const toDos = await resp.json();
    setToDos(toDos);
  }

    ...

  useEffect(() => {
    getToDos();
  }, [])

  const completed = toDos.filter(todo => todo.isCompleted);
  const notCompleted = toDos.filter(todo => !todo.isCompleted);

    ...

  return (

    ...

     <div className={styles.scrolly}>
        {notCompleted.map((todo, index) => 
          <ToDo 
            key={todo.key} 
            content={`${index + 1}. ${todo.content}`} 
            isCompleted={todo.isCompleted} 
            // onChange={() => updateToDo(todo)} To Be Implemented
            // onDelete={() => deleteToDo(todo.key)} To Be Implemented
          />
        )}
     </div>

    ...

     <div className={styles.scrolly}>
       {completed.map((todo, index) => 
         <ToDo 
           key={todo.key} 
           content={`${index + 1}. ${todo.content}`} 
           isCompleted={todo.isCompleted}
           // onChange={() => updateToDo(todo)} To Be Implemented
           // onDelete={() => deleteToDo(todo.key)} To Be Implemented
         />
       )}
    </div>

    ...

    )

}

The serverless function handler in pages/api/todos/index.js looks as follows:

// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import { Deta } from 'deta';

const deta = Deta(process.env.DETA_PROJECT_KEY);

const base = deta.Base('todos');

export default async (req, res) => {
  let { body, method } = req;
  let respBody = {};

  if (method === 'GET') {

    const {value: items} = await base.fetch([]).next();
    respBody = items;
    res.statusCode = 200;

  }

...

  res.json(respBody);
}

Here the GET request is handled in the function, using a Deta Base's fetch to return all items in a database called todos .

Updating a To Do

To update a To Do's completion status, we create a function updateToDo that will call PUT api/todos/{tid} based on our ToDo component triggering an onChange function (which is implemented by a checkbox being checked / unchecked):

export default function Home() {

    ...
    const updateToDo = async (todo) => {
            let newBody = { 
               ...todo,
               isCompleted: !todo.isCompleted
            };
            const resp = await fetch(`api/todos/${todo.key}`, 
               {
                   method: 'put', 
                   body: JSON.stringify(newBody)
               }
            );

            await getToDos();
        }
    ...
    return (
    ...

            <ToDo 
                key={todo.key} 
                content={`${index + 1}. ${todo.content}`} 
                isCompleted={todo.isCompleted} 
                onChange={() => updateToDo(todo)}
        />
    ...
    )
}

The function will send a PUT to with the opposite pages/api/todos/[tid].js :

import { Deta } from 'deta';

const deta = Deta(process.env.DETA_PROJECT_KEY);

const base = deta.Base('todos');

export default async (req, res) => {

  let { body, method, query: { tid } } = req;
  let respBody = {};

  if (method === 'PUT') {

    body = JSON.parse(body);
    respBody = await base.put(body);
    res.statusCode = 200;

  } else if (method === 'DELETE') {

    // To Be Implemented

  }

  res.json(respBody);
}

In this handler, we pass the unchanged body through our put method to store our updated to do in our database. Because the body contains the key this will correctly overwrite the old record.

Deleting a To Do

Finally, to delete a To Do, let's add the api call that will call DELETE api/todos/{tid} based on a button click:

export default function Home() {

  ...


  const deleteToDo = async (tid) => {
    const resp = fetch(`api/todos/${tid}`, {method: 'delete'});
    setTimeout(getToDos, 200);
  }

    ...
    return (
    ...
                <ToDo 
                  key={todo.key} 
                  content={`${index + 1}. ${todo.content}`} 
                  isCompleted={todo.isCompleted} 
                  onChange={() => updateToDo(todo)}
                  onDelete={() => deleteToDo(todo.key)}
                />  
    ...
    )

}

The function deleteToDo, when called, will make a DELETE request to pages/api/todos/{tid} , whose handler looks as follows:

import { Deta } from 'deta';

const deta = Deta(process.env.DETA_PROJECT_KEY);

const base = deta.Base('todos');

export default async (req, res) => {

  let { body, method, query: { tid } } = req;
  let respBody = {};

  if (method === 'PUT') {

  ...

  } else if (method === 'DELETE') {

    respBody = await base.delete(tid);
    res.statusCode = 200;

  }

  res.json(respBody);
}

In this handler, we pass use the delete method from the Deta SDK.

Final Things

All the logic is implemented at this point and you can deploy the resulting application yourself to Vercel.

You can also do it in a few clicks: just grab a Deta project key, click the button below, and set the project key as an environment variable-- DETA_PROJECT_KEY--during Vercel's flow.

We can't forget to mention that you can now view and manage your to dos from Deta Base's GUI, Guide. If you add or modify one of your To Dos from here, the changes will load in the Vercel app on page refresh.

The last thing worth mentioning is that this app uses a standard vanilla React pattern for managing the application state to keep things simple. However, we can take advantage of some smart things Next enables (in tandem with libraries like useSWR) to improve performance. If you've deployed this app, you'll notice the delays on create, modification and deletion, as the serverless functions take around 300ms to respond. With some improvements, we can boost performance and create a feeling of an instant response on the client side. Stay tuned for round 2.

Introducing Base UI: a GUI for your Deta Base

Max — Wed, 30 Sep 2020 15:44:58 +0000

What's Base UI?

Base UI (beta) is a graphical user interface for Deta Base. Base UI was inspired by the struggles of many developers in interacting with the data powering their apps, outside the confines of the app itself.

A video tour is available at the end of the post.

Motivation

Since shipping the earliest alpha of Deta & Deta Base, devs have resonated with the simplicity of spinning up a database using Deta. In it's purest form, there is no marginal config step required, it's just code.

This approach is great when you want to design state from the comforts of your text editor. While Base has provided a persistent state solution for some inspirational apps so far, we realized it was falling short on another dimension we didn't initially expect.

The biggest shortcoming we've heard from users about Base is the lack of a UI. We often heard 'I want to be able to easily see and interact with the data my app generates'. We noticed some users would hack around this shortcoming, adding auxiliary logic to their application or a side script to quickly inspect or modify the records their main app generates.

But going through both a text editor and running a script to inspect and modify records is less than ideal. Two members of our community— turned summer fellows—both took it a step further, each hacking their own Base records viewers together (first w/ source; second w/ source).

Suffice to say, we are extremely excited to address this need and launch Deta's official Base GUI solution into beta, building off the work of the second solution. With Base Guide, you can rapidly inspect, add, delete, and modify the records contained in your Base.

Inspecting Records

To view a Base's records, all you need to do is open an individual Base from the Deta Project Sidebar. By default the Base's records will load into Base UI.

If you want to inspect a slice of the data within a Base, you can use Base's queries to do so, i.e.:

[{"cuisine": "Italian", "have_visited": false}]

Adding Records

To add records to a base, click the '+ Add' button and a new row will appear at the top of your Base's UI.

The new row will be treated as a candidate edit, with a yellow background, which can be permanently saved by clicking the 'Save' button.

Modifying Records

For primitive types (strings, booleans, and numbers), you can modify any record directly from within a cell.

For advanced editing, i.e. to change the type of a given value, or edit arrays or objects, you can expand the cell and do so.

Once you are satisfied with your edits, simply click the 'Save Edits' button, as before, to modify these records in your Base. If you want to discard all your edits locally, click 'Undo Changes'.

Deleting Records

For every record displayed in Base UI, there is a checkbox on the left side. By clicking the checkbox, the record will be highlighted in red as a delete candidate. To go forward with the deletion, simply click the 'Delete' item.

For candidate adds, edits, and deletes, the 'Undo' button will revert the Base Guide to the state that was last pulled.

Start with Base UI Today

To get started with Base UI, simply log-in / sign-up with Deta, grab a project key, and create a Deta Base in your Python or Node.js app. Deta Guide will be accessible for any Base you create.

Tour

Thanks

We'd love to thank the Deta community for the incredible feedback that led to this initiative as well as Samarth Jajoo for the initial implementation which we built on top of!

Building a micro Roam Research Clone from Scratch

Max — Mon, 24 Aug 2020 16:20:45 +0000

Background

At Deta, we believe the individual developer should be empowered to create their own tools in the cloud. We also see that the tools for building these tools are more approachable than ever. What follows is a description of building my own tool, Yarc, to demonstrate this and to scratch an itch within my own workflow.

Roam Research is a notes app which describes itself as a 'tool for networked thought'. Roam aims to free your notes from a rigid hierarchical structure (what they call 'the file cabinet approach') in tools like Evernote. Using Roam, one can easily and deeply network notes using advanced hyperlinking capabilities. For instance, in any given note, one can see all the other notes (backlinks) which link to the said note (bi-directional linking).

I personally liked the bi-directional linking in Roam, but I wanted something lighter weight with the ability to open up the hood and add features as I saw fit, like accessing the raw text of my notes over API. I saw many other permutations of tools that had offered their own take on the bi-directional linking in Roam (see Obsidian, Foam); I named my own clone Yarc (yet another roam clone).

With Yarc, I'm not declaring that this project comes remotely close to matching what the team at Roam has done. Imitation is the sincerest form of flattery, and Roam offers far more advanced capabilities than Yarc will likely every have.

Project Design

What I needed was for the app was simple, consisting of three significant parts:

Core Functionality: a standard for writing notes, uniquely addressing them, and bi-directionally linking them
Backend: the backend needed to serve a note and its contents as well as process updates (content, links, and backlinks) to a given note
Frontend: a client / UI to easily view and update the notes

Core Functionality

First, for the notes themselves, I decided to use Markdown as it is a standard with a syntax versatile enough to support text documents with code snippets, hyper links, pictures, etc, built-in. There is tremendous support for Markdown across many tools, some of which I use in Yarc; if I ever need to migrate any notes out of Yarc, there shouldn't be major conflicts using other tools.

The basic feature in Roam I wanted to emulate was the ability to bi-directionally link notes, triggered by the indicator [[]]. For example, if Note A includes text: bla bla [[Note B]], then Note A should link to Note B, and Note B should have Note A in its list of Backlinks. For this to work, I needed two things:

each note needs a unique address tied to a name
a way to process [[name]] tags as links to that address

The principle which drives Yarc follows from recognizing that Markdown and HTML provide great support for HTTP links out of the box. Consequently, I could give each note a unique HTTP address (e.g: :base_url/notes/:note_name ) and prior to rendering a Markdown note as HTML, pre-process [[note_name]] links by converting them to traditional markdown links [note_name](:base_url/notes/:note_name), while also keeping track of all backlinks in the backend.

To recognize all the unique [[]] links in a markdown note, I wrote a short JavaScript function with a bit of regex that spits out the set of unique [[]] links. When we save a note, we can tell our backend to add the current note as a backlink to all the unique links in the current note.

const getUniqueLinks = rawMD => {
  const uniqueLinks = [...new Set(rawMD.match(/\[\[(.*?)\]]/g))];
  return uniqueLinks;
};

Additionally, we can use the array of current links to create the substitution from a [[]] link to a normal Markdown link ([]()) prior to converting the Markdown to HTML.

This function takes our unique Markdown with [[]] tags and spits out standard Markdown:

const linkSub = (rawMD, links, baseUrl) => {
  let newMD = rawMD;
  for (const each of links) {
      let replacement;
      const bareName = each.substring(2, each.length - 2);
      replacement = `[${bareName}](${baseUrl}notes/${encodeURI(bareName)})`;
      newMD = newMD.split(each).join(replacement);
  }
  return newMD;
};

These two functions form the core of Yarc: recognizing the set of bi-directional links in a note and converting the syntax we use into regular Markdown (which can be converted to HTML). Everything else is tying the database, routes, and UI together.

Backend: Deta + FastAPI + Jinja2

For the backend I used:

Deta to host the compute + api and database
FastAPI as the web framework to do the heavy lifting
Jinja2 to generate the note templates to serve to the client

Database (Deta Base)

I used Deta Base to store permanent data. The database operations are in the note.py file and handle reading and writing the raw note data. The basic data schema for a note is stored under a key (which is the urlsafe version of a note's name), and has the following fields:

    name: str
    content: str
    links: list = []
    backlinks: list = []

Routing and Main Functionality (FastAPI on a Deta Micro)

I used Deta Micros to run the FastAPI application and host it at a unique URL. The routes and business logic for the application are built using FastAPI and are in main.py. FastAPI describes itself as a 'micro framework' and their philosophy of sane defaults and a low learning curve were great in contributing to a quick process of building Yarc. If you know Python, building a web app with FastAPI is a very straightforward process.

There are three primary routes & functionalities in Yarc's backend:

GET /: returns the homepage
GET /notes/{note_name}: returns a note with a given name (and creates the note first if it doesn't exist). Accepts an optional query parameter json=true which returns the note information as JSON.
PUT /{note_name}: receives a note payload, updates the database entry of a given note and all other notes that the note links to (as the backlinks fields need to be updated).

This third route, which keeps track of the correct links & backlinks across notes, was the most involved piece, so I'll include this operation here:

@app.put("/{note_name}")
async def add_note(new_note: Note):
    old_note = get_note(new_note.name) 
    old_links = old_note.links if old_note else []
    removed_links = list_diff(old_links, new_note.links)
    added_links = list_diff(new_note.links, old_links)

    for each in removed_links:
        remove_backlink(each, new_note.name)

    db_update_note(new_note)

    for each in added_links:
        add_backlink_or_create(each, new_note.name)

    return {"message": "success"}

Templating

To serve the notes I used Jinja2 to template HTML files with the note data and the frontend JavaScript code, written in Hyperapp. By injecting the frontend JavaScript into the template instead of importing it as a module, I saved one API call on every page load.

Libraries Used:

Frontend: Hyperapp

For the client side of the web app I used (and learned) Hyperapp. Hyperapp is a super lightweight (1kb, no build step!) framework for building interactive applications in a functional, declarative manner. Having experience using React (+ Redux) where a Component combines state management, a description of the DOM, and side effects, I'd say Hyperapp more clearly de-lineates their concepts (views, actions, effects, and subscriptions). As with other frameworks, there's a bit of a learning to get familiar with their concepts, but once you get a handle on them, it is a joy to work with. Like FastAPI, it lives up to its name, and you can build and ship useful applications super quickly.

For interacting with a note (code in note.js), the Hyperapp application has two primary 'modes' as an end user (toggled by triggering a Hyperapp action):

Edit Mode: This mode displays the raw markdown of a note, allowing the user to write notes
View Mode: This mode displays the note as HTML, allowing the user to follow links

Edit Mode

Editing mode is triggered when the user clicks the edit button, which dispatches the Edit action in Hyperapp. This action also triggers an effect, attachCodeJar, which attaches the text editor I used, CodeJar, to the correct DOM element and binds another action, UpdateContent, to the text editor such that the current state of the text editor is saved into the state tree in Hyperapp.

// Edit Action
const Edit = state => {
  const newState = {
    ...state,
    view: "EDIT"
  };
  return [newState,
    [attachCodeJar, { state: newState, UpdateContent }]
  ];
};

// attachCodeJar Effect
const attachCodeJar = (dispatch, options) => {
  requestAnimationFrame(() => {
    var container = document.getElementById("container");
    container.classList.add("markdown");

    const highlight = editor => {
        editor.textContent = editor.textContent;
        hljs.highlightBlock(editor);
    };

    jar = CodeJar(container, highlight);
    jar.updateCode(options.state.note.content);
    jar.onUpdate(code =>
      dispatch(options.UpdateContent(options.state, code))
    );

  });
};

// UpdateContent Action
const UpdateContent = (state, newContent) => {
  return {
    ...state,
    note: {
      ...state.note,
      content: newContent
    }
  };
};

View Mode

View Mode is triggered by clicking the save button, which dispatches the Save action in Hyperapp and triggers two effects: attachMarkdown and updateDatabase.

attachMarkdown removes the text editor from the DOM element and replaces it with the HTML output from converting the latest note Markdown in state using Showdown.
updateDatabase sends the latest note Markdown, links, and backlinks to the backend to save in the database, via an API call.

Libraries Used for the Frontend

Summary

The full source code of the project is here and includes other bits of the application like the homepage, searching, and interacting with the notes over CLI. It also provides instructions for deployment on Deta if you want to deploy your own instance of Yarc.

There are a number of great tools out there that let you build your own cloud tools remarkably quickly, with little overhead. At Deta, we try to provide no-fuss infrastructure to get your code running. I personally found both FastAPI (for the server) and Hyperapp (for the client) to be really complementary frameworks for building lightweight, personal apps; both are great, no-fuss, options that provide a lighting quick route to getting something out.