docs: review

Author: rehanvandermerwe

.husky/pre-commit

@@ -1,9 +1,5 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-npm run default
-npm run eslint
-node_modules/.bin/ts-node ./scripts/index.ts -c validate-src
-npm run build-jsii
-npm run docgen
+npm run pre-commit-check
 git add -u

.projenrc.ts

@@ -14,7 +14,7 @@ const project = new awscdk.AwsCdkConstructLibrary({
   packageManager: javascript.NodePackageManager.NPM,
   releaseToNpm: true,
   npmAccess: NpmAccess.PUBLIC,
-  repositoryUrl: 'https://github.com/rehan.merwe/serverless-website-analytics.git',
+  repositoryUrl: 'https://github.com/rehanvdm/serverless-website-analytics.git',
   excludeTypescript: ['src/src/**/*'],
   devDeps: ['husky', 'execa@5', 'fs-extra', '@types/fs-extra', 'esbuild', 'yargs', 'esbuild-runner'],
   eslint: true,

README.md

@@ -1,6 +1,6 @@
 # Serverless Website Analytics
 
-This is a CDK serverless website analytics solution that can be deployed to AWS. This construct creates backend,
+This is a CDK serverless website analytics construct that can be deployed to AWS. This construct creates backend,
 frontend and the ingestion APIs.
 
 This solution was designed for multiple websites with low to moderate traffic. It is designed to be as cheap as
@@ -14,7 +14,7 @@ You can see a LIVE DEMO [HERE](https://demo.serverless-website-analytics.com/).
 - The target audience is small to medium websites with low to moderate traffic (less than 10M views)
 - Lowest possible cost
 - KISS
-- No direct server side state
+- No direct server-side state
 - Low maintenance
 
 The main objective is to keep it simple and the operational cost low, keeping true to "scale to 0" tenants of serverless,
@@ -24,7 +24,7 @@ even if it goes against "best practices".
 
 ### Serverside setup
 
-> ⚠️ Requires your project `aws-cdk` and `aws-cdk-lib` > 2.79.1
+> ⚠️ Requires your project `aws-cdk` and `aws-cdk-lib` packages to be greater than  2.79.1
 
 Install the [CDK construct library](https://www.npmjs.com/package/serverless-website-analytics) in your project:
 ```
@@ -76,41 +76,42 @@ export class App extends cdk.Stack {
 
 Quick option rundown:
 - `sites`: The list of allowed sites. This does not have to be a domain name, it can also be string. It can be anything
-  you want to use to identify a site. The client side script that send analytics will have to specify one of these names.
+  you want to use to identify a site. The client-side script that sends analytics will have to specify one of these names.
 - `allowedOrigins`: The origins that are allowed to make requests to the backend Ingest API. This CORS check is done as an extra
   security measure to prevent other sites from making requests to your backend. It must include the protocol and
   full domain. Ex: If your site is `example.com` and it can be accessed using `https://example.com` and
-  `https://www.example.com` then both need to be listed. A value of `*` is specifies all origins are allowed.
-- `auth`: The auth configuration which defaults to none. If you want to enable auth, you can specify either Basic Auth or
-  Cognito auth but not both.
+  `https://www.example.com` then both need to be listed. A value of `*` specifies all origins are allowed.
+- `auth`: Defaults to none. If you want to enable auth, you can specify either Basic Auth or Cognito auth but not both.
   - `undefined`: If not specified, then no authentication is applied, everything is publicly available.
   - `basicAuth`: Uses a CloudFront function to validate the Basic Auth credentials. The credentials are hard coded in
-    the Lambda function. This is not the recommended for production, it also only secures the HTML page, the API is still
+    the Lambda function. This is not recommended for production, it also only secures the HTML page abd API is still
     accessible without auth.
   - `cognito`: Uses an AWS Cognito user pool. Users will get a temporary password via email after deployment. They will
-    then be prompted to change their password on first login. This is the recommended option for production as it uses
+    then be prompted to change their password on the first login. This is the recommended option for production as it uses
     JWT tokens to secure the API as well.
 - `domain`: If specified, it will create the CloudFront and Cognito resources at the specified domain and optionally
   create the DNS records in the specified Route53 hosted zone. If not specified, it uses the default autogenerated
   CloudFront(`cloudfront.net`) and Cognito(`auth.us-east-1.amazoncognito.com`) domains. You can read the website URL
   from the stack output.
 
-For a full list of options see the [API.md](docs/API.md) docs.
+For a full list of options see the [API.md](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs/API.md#api-reference-) docs.
+
+You can see an example implementation of the demo site [here](https://github.com/rehanvdm/serverless-website-analytics-test)
 
 ### Client side setup
 
-> ⚠️ IMPORTANT! **After** the client sent the first data, you have to click on the "Add Partitions" button in the
-> frontend to auto discover and add the site, month, day partitions. Otherwise, the data will not show up in the charts.
+> ⚠️ IMPORTANT! **After** the client sent the first page data, you have to click on the "Add Partitions" button in the
+> frontend to auto-discover and add the site, month and day partitions. Otherwise, the data will not show up in the charts.
 > This operation has to be repeated at the beginning of every month.
 
-Install the [client side library](https://www.npmjs.com/package/serverless-website-analytics-client):
+Install the [client-side library](https://www.npmjs.com/package/serverless-website-analytics-client):
 ```
 npm install serverless-website-analytics-client
 ```
 
 Irrelevant of the framework, you have to do the following to track page views on your site:
 
-1. Initialize the client only once with `analyticsPageInit`. The site name must correspond with one that you specified
+1. Initialize the client only once with `analyticsPageInit`. The site name must correspond with the one that you specified
    when deploying the `serverless-website-analytics` backend. You also need the URL to the backend. Make sure your frontend
    site's `Origin` is whitelisted in the backend config.
 2. On each route change call the `analyticsPageChange` function with the name of the new page.
@@ -145,21 +146,26 @@ app.mount('#app');
 
 The architecture consists of four components: frontend, backend, ingestion API and the client JS library.
 
-![serverless-website-analytics.drawio.png](docs%2Fimgs%2Fserverless-website-analytics.drawio.png)
+![serverless-website-analytics.drawio.png](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs%2Fimgs%2Fserverless-website-analytics.drawio.png)
+
+See the [highlights](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs/CONTRIBUTING.md#highlights)
+and [design decisions](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs/CONTRIBUTING.md#design-decisions)
+sections in the [CONTRIBUTING](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs/CONTRIBUTING.md#design-decisions)
+file for detailed info.
 
 ### Frontend
 
-AWS CloudFront is used to host the frontend. The frontend is a SPA Vue 3 app that is hosted on S3 and served through
+AWS CloudFront is used to host the frontend. The frontend is a Vue 3 SPA app that is hosted on S3 and served through
 CloudFront. The [Element UI Plus](https://element-plus.org/en-US/) frontend framework is used for the UI components
-and https://plotly.com/javascript/ for the charts.
+and [Plotly.js](https://plotly.com/javascript/) for the charts.
 
-![frontend_1.png](docs/imgs/frontend_1.png)
-![frontend_2.png](docs/imgs/frontend_2.png)
-![frontend_3.png](docs/imgs/frontend_3.png)
+![frontend_1.png](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs/imgs/frontend_1.png)
+![frontend_2.png](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs/imgs/frontend_2.png)
+![frontend_3.png](https://github.com/rehanvdm/serverless-website-analytics/blob/main/docs/imgs/frontend_3.png)
 
 ### Backend
 
-This is a Lambda-lith hit through the Lambda Function URLs (FURL) by reverse proxing through CloudFront. It is written
+This is a Lambda-lith hit through the Lambda Function URLs (FURL) by reverse proxying through CloudFront. It is written
 in TypeScript and uses [tRPC](https://trpc.io/) to handle API requests.
 
 The Queries to Athena are synchronous, the connection timeout between CloudFront and the FURL has been increased
@@ -171,20 +177,22 @@ There are three available authentication configurations:
 - **AWS Cogntio**, recommended for production
 
 ⚠️ Partitions are not automatically created in Athena, they have to be created manually by the user by clicking the
-"Create/Refresh Partitions" button in the frontend. This has to be done when ever a new site is added or a new month
+"Create/Refresh Partitions" button in the frontend. This has to be done whenever a new site is added or a new month
 starts.
 
 ### Ingestion API
 
-Similarly to the backend, it is also a TS Lambda-lith that is hit through the FURL by reverse proxing through CloudFront.
+Similarly to the backend, it is also a TS Lambda-lith that is hit through the FURL by reverse proxying through CloudFront.
 It also uses [tRPC](https://trpc.io/) but uses the  [trpc-openapi](https://github.com/jlalmes/trpc-openapi) package to
 generate an OpenAPI spec. This is used to generate the API types used in the [client JS package](https://www.npmjs.com/package/serverless-website-analytics-client).
 and can also be used to generate other language client libraries.
 
 The lambda function then saves the data to S3 through a Kinesis Firehose. The Firehose is configured to save the data
-in a partitioned manner, by site, year and month. The data is saved in parquet format. Location data is obtained by
-looking the IP address up in the [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) database. We don't
-store any Personally Identifiable Information (PII) in the logs, the IP address is never stored.
+in a partitioned manner, by site, year and month. The data is saved in parquet format, buffered for 1 minute, which means
+the date will be stored after about 1min ± 1min.
+
+Location data is obtained by looking the IP address up in the [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) database.
+We don't store any Personally Identifiable Information (PII) in the logs or S3, the IP address is never stored.
 
 ## Sponsors
 
@@ -193,7 +201,6 @@ Proudly sponsored by:
 all your AWS credentials and more.
 - Interested in [sponsoring](https://rehanvdm.com/contact-me)?
 
-
 ## Contributing
 
 See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for more info on how to contribute + design decisions.