Project structure and conventions

This is a ruleset that defines guides of a project structure management. Why does it exist? There are several reasons for that:

1. It is easier for teammates to help if you follow the common structure
2. It helps us to perform a code review and ensure the highest quality of your code
3. It implements the leading and proven software engineering practices

The philosophy

There are several generic, vague rules that put other things in structure. All other rules and minor things would be easy to understand if you remember those.

Follow the SOLID approach

Create single-responsibility, open to extension, closed for modification, replaceable components with specific interfaces that depend on abstractions. That's what the SOLID principle does. Ignore this approach right after you master it.

Re-use reliable things as much as possible

Do not write code if you can. Take something that is written, re-use, override. 99% of challenges were solved by others previously.

Understand what have you copied

If you copy something, read the documentation and understand how it works. No need to dive into details, but you need to understand the purpose and the outcomes of everything that's copied.

Keep structures flat

Do not create structures if you can. Do not create a folder if there are only 1-2 files in it.

Follow one logic

If you follow logic, follow it everywhere. If the logic doesn't work, come up with another one that covers all cases or states that there is no logic behind it.

Project Structure in detail

The basic project level would look like this:

projectname
├── (.files)           – config files you don't need to touch
├── node_modules       – installed modules, no need to touch
├── packages           – folder for all independent apps
│   ├── cms            – content management app folder
│   └── website        – front-end app folder
├── .env               – main environment file
├── .env.dist          – main environment template
├── package.json       – project configurations and global scripts
├── README.md          – project readme
├── LICENSE            – license details
├── (*.lock files)     – autogenerated files
└── (*.yaml files)     – deployment and configs

Main notes:

• Most of the files on this level change rarely. If you write to a file here constantly, then there is a probability you are doing something wrong.
• .env file is your own local file that should not go to git. You can find more about .env files in this article
• .lock files are autogenerated. You can always delete and re-generate them in case you face conflicts.

The App level (cms, website, or something new) looks like this:

appname
├── (.folders)         – temporary folders you can ignore
├── build              – a folder with the generated build
├── node_modules       – installed modules, no need to touch
├── src                – your main folder
│   ├── components     – a folder with all custom components
│   ├── graphql        – a folder with all connectivity items
│   ├── types          – a folder with all custom type definitions
│   ├── ...            – other project-specific folders
│   └── index.tsx      – app entry point
├── .env               – main environment file
├── .env.*             – environment templates
├── Dockerfile         – containerization instructions for further deployment
├── package.json       – app configurations and global scripts
├── README.md          – app readme
├── tsconfig.json      – app typescript settings, don't touch
└── vite.config.ts     – app building config

Notes:

• you would find some app-specific files here and there, because of each app specifics.
• `.env' file should be created manually followed by instructions.
• package.json is the main place to add npm packages, run scripts, etc.
• README.md should answer questions on what app does and how to run it.
• We strongly advise understanding how the app is compiled by reading the vite.config.ts file.

The source code level (src) for a front-end app looks like this:

src
├── components              – a folder with all custom components
│   ├── app                 – base single-page app component
│   │   ├── index.less      – base CSS container that implements Ant styles and overrides
│   │   └── index.tsx       – generic app code
│   ├── layouts             – layouts folder
│   │   ├── index.tsx       – container for exporting
│   │   ├── <CompName>.tsx  – layout code
│   │   ├── <CompName>.less — layout styles
│   │   └── assets          — layout assets
│   ├── <compname>          – custom component you are coding
│   │   ├── <CompName>.tsx  – custom component code
│   │   ├── <CompName>.less — custom component styles
│   │   └── assets          — custom component assets
│   └── ...                 — your other component folders
├── graphql                 – a folder with all connectivity items
│   ├── fragments           – graphql fragments go here
│   ├── mutations           – graphql mutations go here
│   ├── queries             – graphql queries go here
│   └── index.tsx           – autogenerated, do not touch
├── types                   – a folder with all custom type definitions
│   └── <type>.d.ts         – type definition for TS autocomplete
├── pages                   – a folder to keep all pages
│   └── <pagename>          – a folder for a page
│       ├── index.tsx       – page implementation
│       └── (something).tsx – additional page related items (hooks, contexts)
├── index.tsx               – app entry point
└── index.less              – container for app-level variables

Notes:

• keed components and pages folders flat, do not create a folder with folders inside.

Naming conventions for a project

• Files should be named with lowerCamelCase convention
• Component files should be named with UpperCamelCase convention
• .less file should have the same name as .tsx file