Skip to content

Commit

Permalink
Merge pull request #64 from marmelab/doc
Browse files Browse the repository at this point in the history 
Feat(doc): Improve documentation
  • Loading branch information
@slax57
slax57 authored Aug 14, 2024
2 parents a518ce7 + 30cad89 commit d3fd05b
Show file tree
Hide file tree
Showing 12 changed files with 254 additions and 230 deletions.
237 changes: 23 additions & 214 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ https://user-images.githubusercontent.com/99944/116970434-4a926480-acb8-11eb-8ce

You can test it online at https://marmelab.com/react-admin-crm.

## Local Supabase Setup
## Install Project

To run this project locally, you will need the following tools installed on your computer:

Expand All @@ -29,9 +29,19 @@ make install

This will install the dependencies for the frontend and the backend, including a local Supabase instance.

## Running the App In Development Mode

Start the app locally with the following command:
## Developing with Atomic CRM

### Local Development Setup

1. [Supabase Configuration](./doc/developer/dev-01-supabase-configuration.md)
2. [Customizing the CRM](./doc/developer/dev-02-customizing.md)
3. [Creating Migrations](./doc/developer/dev-03-supabase-migrations.md) *(optional)*
4. [Contact Import Customization](./doc/developer/dev-04-contact-import.md) *(optional)*
5. [Using Fake Rest Data Provider for Development](./doc/developer/dev-O5-data-providers.md) *(optional)*
6. [Learn More About Architecture Decisions](./doc/developer/dev-06-architecture-choices.md) *(optional)*

Once you app is configured, start the app locally with the following command:

```sh
make start
Expand All @@ -48,222 +58,21 @@ If you need debug the backend, you can access the following services:
- Attachments storage: [http://localhost:54323/project/default/storage/buckets/attachments](http://localhost:54323/project/default/storage/buckets/attachments)
- Inbucket email testing service: [http://localhost:54324/](http://localhost:54324/)

## Testing

This project contains unit tests. Run them with the following command:

```sh
make test
```

## Deploying to Production

### Supabase Configuration

To configure Supabase, please have a look at [dedicated configuration guide](./doc/supabase-configuration.md).

### Testing Production Mode

If you want to test you code locally using production mode and the remote Supabase instance, you can run the following command:

```sh
make prod-start
```

Note: It will apply migrations and deploy edge functions.

You can then access the app via [`http://localhost:3000/`](http://localhost:3000/).

### Deploying The Frontend

The frontend of the CRM is a Single-Page App that can be deployed to any CDN, or to GitHub Pages.

First, build the fontend bundle with:

```sh
make build
```

This will create a `dist` directory with the built application made of static HTML, CSS, and JS files.

Then, upload this directory to the CDN of your choice. If you want to deploy it to the `gh-pages` branch of the your repository, you can use the following command:

```sh
npm run ghpages:deploy
```

### Deploying Updates

If you've modified the code, run the following command to deploy a new version of your CRM:

```sh
make prod-deploy
```

It will apply migrations, deploy edge functions and push the built applications to the `gh-pages` branch.

## GitHub Actions

Learn how to [configure GitHub Actions for Atomic CRM](./doc/github-actions.md).

## Customizing

You can customize the title, logo, theme, and domain of the CRM app by passing custom props to the `<CRM>` component:
### Deploying to Production

```tsx
// App.tsx
import React from 'react';
import CRM from './CRM';
1. [Manual Production Deploy](./doc/developer/prod-01-manual-deploy.md)
2. [GitHub Actions Configuration](./doc/developer/prod-02-github-actions.md) *(optional)*
3. [Email Inbound Configuration](./doc/developer/prod-03-email-inbound.md) *(optional)*

const App = () => (
<CRM
title="Custom CRM Title"
logo="custom-logo.png"
/>
);
### Testing

export default App;
```

## Domain & Process

In addition to the design, you can easily customize various aspects relevant to your business domain. The behavior is the same as described above. You can modify the following:

| Props | Description | Type |
|-----------------------|-----------------------------------------------------------------------|-----------------|
| contactGender | The gender options for contacts used in the application. | ContactGender[] |
| companySectors | The list of company sectors used in the application. | string[] |
| darkTheme | The theme to use when the application is in dark mode. | RaThemeOptions |
| dealCategories | The categories of deals used in the application. | string[] |
| dealPipelineStatuses | The statuses of deals in the pipeline used in the application | string[] |
| dealStages | The stages of deals used in the application. | DealStage[] |
| lightTheme | The theme to use when the application is in light mode. | RaThemeOptions |
| logo | The logo used in the CRM application. | string |
| noteStatuses | The statuses of notes used in the application. | NoteStatus[] |
| taskTypes | The types of tasks used in the application. | string[] |
| title | The title of the CRM application. | string |

```tsx
import { CRM } from './root/CRM';
import { ThemeOptions } from '@mui/material/styles';

const lightTheme: ThemeOptions = {
palette: {
mode: 'light',
},
};

const darkTheme: ThemeOptions = {
palette: {
mode: 'dark',
},
};

const App = () => {
return (
<CRM
contactGender={[
{ value: 'male', label: 'He' },
{ value: 'female', label: 'She' },
]}
companySectors={['Technology', 'Finance']}
darkTheme={darkTheme}
dealCategories={['Copywriting', 'Design']}
dealPipelineStatuses={['won']}
dealStages={[
{ value: 'opportunity', label: 'Opportunity' },
{ value: 'proposal-sent', label: 'Proposal Sent' },
{ value: 'won', label: 'Won' },
{ value: 'lost', label: 'Lost' },
]}
lightTheme={lightTheme}
logo="https://example.com/logo.png"
noteStatuses={[
{ value: 'cold', label: 'Cold', color: '#7dbde8' },
{ value: 'warm', label: 'Warm', color: '#e8cb7d' },
{ value: 'hot', label: 'Hot', color: '#e88b7d' },
]}
taskTypes={['Call', 'Email', 'Meeting']}
title="CRM Dashboard"
/>
);
};

export default App;
```

## Adding Sales

To add a new sale to the CRM, you need to use an administrator account. By default, the first account created has this role. If you are starting fresh, a sign-up page will prompt you to create this admin account.

When logged in as an admin, an 'Account Manager' tab will be available. From this page, you can create sales and transfer the administrator role.

![Adding sales](./public/img/adding-sales.png "Adding sales")


## Customizing the Homepage

The first page of the application is managed by the `Dashboard.tsx` component. You can customize it by updating this file.

```jsx
// ./src/dashboard/Dashboard.tsx
import React from 'react';
import { Card, CardContent, Typography } from '@mui/material';

export const Dashboard = () => {
return (
<Card>
<CardContent>
<Typography variant="h5" component="div">
Welcome to the Custom Dashboard!
</Typography>
<Typography variant="body2" color="text.secondary">
This is a customized homepage for your application. You can add any components or content here to suit your needs.
</Typography>
</CardContent>
</Card>
);
};
```

## Import Contacts

From the crm, a user can import a list of contacts via a csv file. This csv file must match the data you use to store your contacts.
By default, we provide a sample file located at `./src/contacts/contacts_export.csv`.

If you change your data structure for a contact, don't forget to modify this sample. You'll also need to modify the import function found in `./src/contacts/useContactImport.tsx`

## Supabase

### Migrations

You can create a new migration using the following command:
```sh
npx supabase migration new <migration_name>
```

You can apply the migrations using the following command:
```sh
npx supabase migration up
```
This project contains unit tests. Run them with the following command:

But you can also apply changes in the database directly using the supabase Dashboard.
Create a new migration using the following command:
```sh
npx supabase db diff | npx supabase migration new <migration_name>
make test
```

### Password Reset And Invitations

An user can be invited to the CRM by an administrator. The user will receive an email with a link to set their password. The password reset feature is also available. You don't have to worry about these processes, Atomic CRM handles them for you, using Supabase.

Please make sure to read and apply the [Login Callback](./doc/supabase-configuration.md#login-callback) and [Customizing Mail Template](./doc/supabase-configuration.md#customizing-mail-template) sections to properly configure the password reset feature.

## Email Features

Atomic CRM supports inbound email features:

- You can add a note to a contact by sending an email to a specific email address
- _More to come!_
## User documentation

Learn more about their usage and setup in the [email features documentation](./doc/email-features.md).
1. [Create First User](./doc/user/01-create-first-user.md)
2. [Import Contacts](./doc/user/02-import-contacts.md)
14 changes: 2 additions & 12 deletions doc/supabase-configuration.md → ...eveloper/dev-01-supabase-configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,15 +52,11 @@ make prod-start

Using a remote Supabase instance can be interesting if you deploy from your computer, or if you want to test your app with production data in production mode.

## Continuous Integration and Continuous Delivery

This repository includes GitHub action workflow for Continuous Delivery. The configuration is explained in the [GitHub Actiosns guide](./github-actions.md) in the same directory.

## Login Callback

### Local Supabase Instance

Go to your [local supabase config](../supabase/config.toml) file:
Go to your [local supabase config](../../supabase/config.toml) file:
1. In `[auth]` section set `site_url` to your application URL
2. In `[auth]`, add the following URL in the `additional_redirect_urls = [<APPLICATION_URL>/auth-callback.html"]`

Expand All @@ -72,7 +68,7 @@ To configure the authentication URL, you can go to your project dashboard at [su

### Local Instance Templates

You can customize the mail templates via the [supabase config](../supabase/config.toml) file. An example of a custom template has been done for the [recovery](../supabase/templates/recovery.html) email.
You can customize the mail templates via the [supabase config](../../supabase/config.toml) file. An example of a custom template has been done for the [recovery](../../supabase/templates/recovery.html) email.

Note: updating the templates requires to restart your supabase instance.

Expand All @@ -82,12 +78,6 @@ If you want more information on how to customize email templates, go to the [rel

If you want to customize the production templates, you can go to your project dashboard at [supabase.com](https://supabase.com/). Then go to **Authentication** > **Email Templates**. You can the choose which template to change using the email template stabs.

## Email Features

Supabase requires additional configuration to enable Atomic CRM's email features. Have a look at the the [email features documentation](./email-features.md) to learn more about their usage and the required setup.

Warning: Free quota for email features is very low. If you encounter problems when creating a user or reseting a password, you can increase the sending limit via a custom STMP server setup. Please refer to the [supabase documentation](https://supabase.com/docs/guides/auth/auth-smtp) if this is your case.

## Fequently Asked Questions

- I have a **Security Definer View** error in **Security Advisor**
Expand Down
Loading

0 comments on commit d3fd05b

Please sign in to comment.