This document provides instructions for the development of a README.md at the root of this project.
Look over the entire code base of this project. Once you've taken a look at everything, follow these instructions to develop the README.
Provide an introduction that includes:
- a tree diagram, with a brief explanation of each area
- a list of all the framework elements in this project and a short description of each, including but not limited to Deno, the Notion client, Hono for the API, blob storage for caching, crons to update the cache, Hono React/JSX for interface templates, and tailwind for styling.
- view routes for the demo
- task routes for Notion webhooks
- logging
- blob storage for the cache, which enables snappy demos
- cron(s) that keep the cache up-to-date
- environment variables, which we use to store connection details for Notion, database ids for essential Notion databases (including the demos and interactions databases), and a webhook API key
- a React front-end that can be customized to a prospective customer, and also acts as a reference for them
When describing the features above, include brief but specific code examples, so the viewer has context. For example, show some code related to /route and /controller separation; and show code related to accessing environment variables. While you're reviewing the code base, keep in mind that each directory has a README.md file that should give you more context, in case the code isn't self-explanatory.
- a Glance demo experience that is personalized to each prospective customer
- Glance's cobrowsing javascript, which allows a visitor and an agent to cobrowse together through the browser
- the Glance PDF viewer, which allows both parties to cobrowse a PDF, which is dynamically generated
- contextual documentation to aid implementation teams
- a PDF "receipt" of the demo to go along with the demo link, so the client has a take-away for future reference
- simple event tracking, so Glance can see which features of the demo get the most engagement
When describing the features above, include brief but specific code examples, so the viewer has context. For example, show some code that includes the feature, like the Glance session javascript, or the CSS class that enables the Glance PDF viewer (e.g., a.pdf
).
For example, theere's a separation of routes and controllers, and there's a separate of controllers and utils. The routes do different jobs, which should be explained. And crons are in their own folder. Most of this may be explained in the tree diagram in the intro, so don't recreate that. But do explain these important conventions so that someone coming into this project will understand what's expected in order to contribute.
As an afterthought at the bottom of the README, note that there are features of this app that are not handled by val.town, and are managed by Notion instead. Those features are:
- email and other alerting, including Slack
- the "Glancer demos" database
- the "Glancer interactions" database, which is where certain demo events (e.g., clicks) are warehoused and visualized
- agent assignments and management, for cobrowsing
Note that this app integrates with Notion to extend Notion in important ways, and most people will not yet understand Notion's limitations around automation and logging, so be clear about that.
Again, only update the README.md file at the root of this project. Don't update any other code. And please do not use emojis in the README.md file.