Gap Analysis

A hackathon demo for finding gaps in corporate anti-phishing processes.

Table of Contents

• Getting Started
  • Clone the Repository
  • Open in VS Code
• Setup
  • Environment Variables
• Important API Endpoints
• Architecture Overview
• Dev Container
  • Prerequisites
  • Open the Dev Container
  • Running Services
  • Setting up database
• Deployment to Docker Containers
  • Building the API Docker Image
  • Building the UI Docker Image
  • Deploying Docker Images
    • Example Deployment to Cloud

Getting Started

Clone the Repository: Clone this repository to your local machine

git clone https://github.com/FrancescoVassalli/GapAnalysis.git
cd GapAnalysis

Open in VS Code: Open the repository in Visual Studio Code

code .

Setup

You can manually run a Docker Compose environment or if you have Visual Studio Code with the Remote Containers extension you can use the Dev Container configuration.

1. Setup your .env - see steps below
2. Have Docker Engine running on your system
3. In this directory docker compose -f .devcontainer/docker-compose.yml up -d
4. Go to localhost:8000 to access the API

Note

Your version of Docker Compose must be 2.0.0 or higher to use the docker compose command. Otherwise, you can use the docker-compose command.

Environment Variables

Create a .env file in the root directory of the project and add the necessary environment variables:

Tip

You can copy .env.example and rename it to .env and fill in the necessary values

ALEMBIC_DATABASE_URL=postgresql://<user>:<passcode>@gap-postgres:5432/postgres
OPENAI_API_KEY=sk-<add-your-key>
ENV=development
GEMINI_API_KEY=AI<add-your-key>

Important API Endpoints

FastAPI has a built-in Swagger UI that can be accessed at localhost:8000/docs or localhost:8000/redoc

Architecture Overview

The project is structured as follows:

• Backend: FastAPI
  • Package Management: Poetry
  • ORM: Alembic
  • Formatting and Linting: Black, isort
  • Testing: Pytest
  • Schema Management: OpenAPI
• Frontend: React
  • Router: TanStack Router
  • State Management: TanStack Query
  • Styles: Tailwind CSS
  • Icons: Scarlab
  • Formatting and Linting: Biome
  • API Client: OpenAPI Generator
• Database: PostgreSQL
• LLM Providers: OpenAI and Google Gemini
• Containerization: Docker

Dev Container

The .devcontainer folder contains a development container configuration for the GapAnalysis project. The devcontainer is configured to provide a consistent development environment using Docker and Visual Studio Code.

Prerequisites

1. Docker: Ensure Docker is installed and running on your system.
2. Visual Studio Code: Install Visual Studio Code.
3. Remote - Containers Extension: Install the Remote - Containers extension in Visual Studio Code.

Open the Dev Container

• Press F1 or CMD/Ctrl + Shift + P to open the command palette
  • Type and select Remote-Containers: Reopen in Container.

This will build and start the devcontainer defined in .devcontainer/devcontainer.json.

You can also click on the Remote Indicator in the bottom-left status bar to get a list of the most common commands. Remote Indicator status bar item: >< to access this menu.

For more information, please see the extension documentation or the devcontainers documentation.

Running Services

This repo contains pre-configured launch commands for the most common applications

In VS Code open the Run and Debug section or by pressing F5

Inside the Debug side bar you can Launch the services defined in .vscode/launch.json

• Run Uvicorn: Launches the FastAPI server

Alternatively you can run poetry run uvicorn main:app --host 0.0.0.0 --port 8000 --reload in the integrated terminal

• Run Website: Generates the OpenAPI client from the FastAPI server and starts the React app

Alternatively you can run npm run generate-client or npm run dev in the integrated terminal

Setting up database

Run this command in the dev container to write the schema to the database

poetry run alembic upgrade head

Deployment to Docker Containers

This project includes Docker configurations for both the API and the UI. The build folder contains the necessary production Dockerfiles.

Building the API Docker Image

To build the Docker image for the API, navigate to the build/api directory and run the following command:

docker build -f build/api.Dockerfile -t gap-analysis-api .

Building the UI Docker Image

Before building the Docker image for the UI, you need to build the static files using npm. Navigate to the root directory of the project and run:

npm run build

After the build process is complete, navigate to the build/ui directory and run the following command to build the Docker image:

docker build -f build/ui.Dockerfile -t gap-analysis-ui .

Deploying Docker Images

Once the Docker images are built, you can deploy them to any cloud provider that supports Docker, such as Digital Ocean, GCP, AWS, and more.

Example Deployment to Cloud

1. Push the Docker images to a container registry (e.g., Docker Hub, Digital Ocean Container Registry, GitHub Container Registry, etc).
2. Run the Docker containers using the pulled images.

docker run -d --rm --name api -p 8000:8000 gap-analysis-api
docker run -d --rm --name ui -p 3000:3000 gap-analysis-ui

This will start the API on port 8000 and the UI on port 3000.

For more detailed instructions on deploying to other cloud providers, refer to their respective documentation.