search

la-famiglia-jst2324 / parma-web

ParmaAI webstack including frontend and REST API backend.
https://parma-web.vercel.app
2 stars 0 forks source link

readme

parma-web

Chore CI Deploy Deploy Major Tag

Functions Lines

Frontend for the ParmaAI data mining and analytics platform.

Topic listing.

Project Description

ParmaAI is a sophisticated platform combining advanced data mining with comprehensive analytics. At its core, Parma Analytics orchestrates the data lifecycle, scheduling and managing data mining modules, and processing the extracted data using tools like ChatGPT for in-depth analysis and report generation. Complementing this, Parma Web provides a user-friendly interface for data management and visualization, making the system's complex functionalities accessible and intuitive. Together, they form a powerful solution for businesses to monitor, analyze, and respond to corporate anomalies, leveraging data-driven insights for strategic decision-making.

parma-web

Parma Web is the interactive user interface of the ParmaAI platform, designed for efficient data source management and visualization. It not only serves as a gateway for users to add, edit, and delete data sources but also ensures that these sources are seamlessly integrated into the platform once they are independently deployed. The repository is crucial for enhancing the user experience, providing clear visualization of analytics results, and facilitating interaction with the backend analytics system. Ideal for contributors focusing on front-end development, Parma Web combines usability and functionality, making complex data insights accessible and understandable for all users.

Related repositories:

Visual Impressions

Auth & Landing Pages

Landing Page Login Page News Feed
Landing Page Login Page News Feed
Profile Page Settings Page
Profile Page Settings Page

UI Navigation

Sidebar Navigation Pure keyboard Interface
Sidebar Navigation Pure keyboard Interface

Companies

Company Dashboard
Company Dashboard
Create Company Company Attachments
Create Company Company Attachments

Buckets (Collections of Companies)

Bucket Dashboard
Bucket Dashboard
Create Bucket Delete Bucket Share Bucket
Create Bucket Delete Bucket Share Bucket

Data Sources

Data Source Dashboard
Data Source Dashboard
Create Data Source Configure Data Source
Create Data Source Configure Data Source

Bucket

Deployment

You can find the latest deployment of this project on parma.software. The staging deployment is available on staging.parma.software.

Getting Started

The following steps will get you started with the project.

  1. Pre-requisites: to be able to contribute to JST in this repository, make sure to comply with the following prerequisites.

    • Configure GitHub via an ssh key. Key based authenticated is highly encouraged. See GitHub Docs for more information.
    • Please make sure to have an GPG key configured for GitHub. See GitHub Docs for more information.
    • Install node v18 via node version manager (nvm) to not cause conflicts with other projects of yours.
    • Make sure you have pnpm installed.
    • (Windows Users Only) have WSL installed on your system and use a linux distribution such as Ubuntu

  2. Clone the repository

    (Windows Users) : Make sure to clone the repository on remote WSL!!

    git clone git@github.com:la-famiglia-jst2324/parma-web.git

  3. Precommit & pnpm setup:

    make install

    Skip to 4. if everything worked

    In case you encounter errors while installing pre-commit, do one of the following :

    1. Install pre-commit with sudo:

      sudo apt install pre-commit
pre-commit # check that it has been correctly installed

    2. Install pre-commit using conda

      "${SHELL}" <(curl -L micro.mamba.pm/install.sh)
bash
micromamba activate
micromamba install pre-commit
pre-commit # check that it has been correctly installed

    3. Mac Users: consider using brew install pre-commit

    Rerun the command to make sure there are no errors :

    make install

  4. Setup Firebase Admin SDK & GCP Credentials:

    The Firebase Admin SDK is used to verify user tokens in the backend (Next API routes). Please download this secrets json file from Notion and place it in /src/api/.secrets/la-famiglia-parma-ai-firebase-adminsdk.json.

    Also make sure to have /src/api/.secrets/la-famiglia-parma-ai-secret-manager.json file with this certificate to be able to access the secret manager.

  5. Start the development server

    make dev

    Open http://localhost:3000 with your browser to see the result.

  6. Optional: Running parts of the pre-commit pipeline manually

    make lint  # runs linting
make build  # builds the project

  7. Test your code and code coverage:

    As the tests require a postgres database to be running, you need a postgres database running locally. For that you can use the docker-compose file in the root directory of this project.

    docker compose up -d

    then before actually running the tests you must set the environment variable with the database credentials. Consider using .env files for that.

    export NEXT_PUBLIC_ENV="staging"
export POSTGRES_URL="postgresql://parma-prod-db:parma-prod-db@localhost:9000/parma-prod-db"
    make test  # runs jest and typescript-coverage-report

  8. Environment Variables Other Than Database URL

    export PARMA_ANALYTICS_BASE_URL=http://127.0.0.1:8000

  9. Optional: Run a production build (used in the CI pipeline)

    make start

    Open http://localhost:3000 with your browser to see the result.

Database Migrations

Follow the steps below to update your local database with recent changes

  1. Make sure your .env file contains:

    POSTGRES_URL="postgresql://parma-prod-db:parma-prod-db@localhost:9000/parma-prod-db"

  2. To apply the recent changes to your local database, run:

    pnpm prisma migrate dev

Database Population

If you want to populate your database, run the following commands, under the root directory, in order:

tsc src/api/db/populate.ts
node src/api/db/populate.js

PR workflow

  1. Create a new branch linear.app offers a button to copy branch names from tickets. In case there is no ticket, please use feel free to use an arbitrary name or create a ticket. GitHub CI doesn't care about the branch name, only the PR title matters.

    # format: e.g. robinholzingr/meta-1-create-archtecture-drafts-diagrams-list-of-key-priorities
git checkout -b <branch-name>

  2. Open a PR and use a conventional commit PR title.

  3. Wait for CI pipeline to pass and if you are happy with your changes request a review.

  4. Merge the PR (using the "Squash and merge" option) and delete the branch. Pay attention to include co-authors if anyone else contributed to the PR.

  5. If you want to release a new version to production, create a new release on GitHub. The release version will be automatically derived from the PR titles (breaking changes yield new major versions, new features yield new minor versions).

Directory Structure

The following directory structure is used in this project:

.
├── node_modules: temporary directory for node dependencies
├── public
│   ├── next.svg
│   └── vercel.svg
├── src: Source code directory for both backend and frontend
│   ├── api: Backend API
│   ├── app: Frontend app
│   ├── components: Reusable components
│   ├── contexts: Frontend context providers
│   ├── lib: generic / non ui functions
│   └── types: Typescript types
├── tests: Tests directory
├── Makefile: Recipes for easy simplified setup and local development
├── README.md
├── next-env.d.ts
├── next.config.js
├── package.json
├── pnpm-lock.yaml
├── postcss.config.js
├── tailwind.config.ts
└── tsconfig.json

Tech Stack

Core libraries that this project uses:

Deployment Concept

This project is deployed on Vercel in @robinholzi's peronsal account. As the hobby (free) plan enough for now, we will stick to it for the time being.

Every commit to a PR branch will trigger a deployment preview. Every new version released on GitHub will trigger a production deployment.

In the future we might add a staging deployment that is deployed to on commit to the main branch. Reach out to @robinholzi if you can benefit from this.

Maybe it would make sense to create a dedicated la-famiglia mail box to which at least the meta team has access to.

We might switch to something else after choosing a full-stack framework like Firebase, Supabase or AWS Amplify.

Remarks

Google Fonts

This project uses next/font to automatically optimize and load Inter, a custom Google Font.

Disclaimer

In case there are any issues with the initial setup or important architectural decisions/integrations missing, please contact the meta team or @robinholzi directly.