Skip to content

Commit 6265456

Browse files
puikinshpuikinsh
authored
Merge pull request #322 from codomposer/fix/doc_project_structure
add project structure to docs
2 parents 341311e + 1eef231 commit 6265456

1 file changed

Lines changed: 320 additions & 0 deletions

File tree

‎docs/getting-started/project-structure.md‎

Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
# Project Structure
2+
3+
This guide explains the folder structure and organization of the Adminator admin dashboard template.
4+
5+
## Overview
6+
7+
Adminator follows a modern, modular architecture with clear separation of concerns. The project is organized into source files, build configuration, and documentation.
8+
9+
```
10+
adminator-admin-dashboard/
11+
├── src/ # Source files
12+
├── dist/ # Built/compiled files (generated)
13+
├── webpack/ # Build configuration
14+
├── docs/ # Documentation
15+
├── node_modules/ # Dependencies (generated)
16+
└── Configuration files
17+
```
18+
19+
## Root Directory
20+
21+
### Configuration Files
22+
23+
| File | Purpose |
24+
|------|---------|
25+
| `package.json` | Node.js dependencies and npm scripts |
26+
| `webpack.config.js` | Webpack entry point |
27+
| `.babelrc` | Babel ES6+ transpiler configuration |
28+
| `eslint.config.mjs` | ESLint 9.x flat configuration for code linting |
29+
| `.stylelintrc.json` | Stylelint configuration for SCSS/CSS linting |
30+
| `.editorconfig` | Editor settings for consistent code style |
31+
| `browserslist` | Target browser versions for compilation |
32+
| `.gitignore` | Git ignore patterns |
33+
| `.gitattributes` | Git attributes configuration |
34+
| `.nvmrc` | Node.js version specification |
35+
36+
### Documentation Files
37+
38+
| File | Purpose |
39+
|------|---------|
40+
| `README.md` | Main project documentation |
41+
| `CHANGELOG.md` | Version history and release notes |
42+
| `LICENSE` | MIT license information |
43+
| `CODE_OF_CONDUCT.md` | Community guidelines |
44+
45+
## Source Directory (`src/`)
46+
47+
The `src/` directory contains all template source files that are compiled into the final application.
48+
49+
### HTML Templates
50+
51+
Located directly in `src/`, these are the template pages:
52+
53+
```
54+
src/
55+
├── index.html # Main dashboard page
56+
├── blank.html # Blank page template
57+
├── 404.html # 404 error page
58+
├── 500.html # 500 error page
59+
├── signin.html # Sign in page
60+
├── signup.html # Sign up page
61+
├── email.html # Email inbox
62+
├── compose.html # Email compose
63+
├── chat.html # Chat application
64+
├── calendar.html # Calendar view
65+
├── charts.html # Charts showcase
66+
├── forms.html # Form elements
67+
├── buttons.html # Button styles
68+
├── ui.html # UI elements showcase
69+
├── basic-table.html # Basic table
70+
├── datatable.html # Data table with features
71+
├── google-maps.html # Google Maps integration
72+
└── vector-maps.html # Vector maps
73+
```
74+
75+
### Assets Directory (`src/assets/`)
76+
77+
Contains all JavaScript, styles, images, and fonts.
78+
79+
```
80+
src/assets/
81+
├── scripts/ # JavaScript files
82+
├── styles/ # SCSS stylesheets
83+
└── static/ # Static assets (images, fonts)
84+
```
85+
86+
## JavaScript Structure (`src/assets/scripts/`)
87+
88+
Modern, jQuery-free vanilla JavaScript architecture.
89+
90+
### Main Application
91+
92+
```
93+
scripts/
94+
├── app.js # Main application entry point
95+
├── index.js # Module exports
96+
└── components/ # Reusable components
97+
├── Sidebar.js # Sidebar navigation component
98+
└── Chart.js # Chart component wrapper
99+
```
100+
101+
### Feature Modules
102+
103+
Each feature has its own directory with an `index.js` entry point:
104+
105+
```
106+
scripts/
107+
├── charts/ # Chart implementations
108+
│ ├── chartJS/ # Chart.js integration
109+
│ ├── easyPieChart/ # Pie chart component
110+
│ └── sparkline/ # Sparkline mini charts
111+
├── chat/ # Chat application logic
112+
├── email/ # Email application logic
113+
├── fullcalendar/ # Calendar integration
114+
├── googleMaps/ # Google Maps integration
115+
├── vectorMaps/ # Vector maps integration
116+
├── datatable/ # Data table functionality
117+
├── datepicker/ # Date picker component
118+
├── masonry/ # Masonry grid layout
119+
├── popover/ # Popover components
120+
├── scrollbar/ # Custom scrollbar
121+
├── search/ # Search functionality
122+
├── sidebar/ # Sidebar behavior
123+
├── skycons/ # Weather icons
124+
└── ui/ # UI components
125+
```
126+
127+
### Utilities and Constants
128+
129+
```
130+
scripts/
131+
├── utils/ # Utility functions
132+
│ ├── dom.js # DOM manipulation helpers
133+
│ ├── date.js # Date utilities (Day.js wrapper)
134+
│ ├── theme.js # Theme management (dark/light mode)
135+
│ └── index.js # Utility exports
136+
└── constants/ # Application constants
137+
└── colors.js # Color definitions
138+
```
139+
140+
## Styles Structure (`src/assets/styles/`)
141+
142+
SCSS-based styling with modular architecture following ITCSS methodology.
143+
144+
```
145+
styles/
146+
├── index.scss # Main style entry point
147+
├── spec/ # Custom styles
148+
│ ├── components/ # Component styles
149+
│ │ ├── sidebar.scss
150+
│ │ ├── topbar.scss
151+
│ │ ├── footer.scss
152+
│ │ ├── forms.scss
153+
│ │ ├── loader.scss
154+
│ │ ├── masonry.scss
155+
│ │ ├── pageContainer.scss
156+
│ │ ├── progressBar.scss
157+
│ │ └── easyPieChart.scss
158+
│ ├── generic/ # Base/reset styles
159+
│ │ └── base.scss
160+
│ ├── screens/ # Page-specific styles
161+
│ │ ├── chat.scss
162+
│ │ └── email.scss
163+
│ ├── settings/ # Variables and configuration
164+
│ │ ├── baseColors.scss
165+
│ │ ├── materialColors.scss
166+
│ │ ├── borders.scss
167+
│ │ ├── breakpoints.scss
168+
│ │ └── fonts.scss
169+
│ ├── tools/ # Mixins and functions
170+
│ │ └── mixins/
171+
│ └── utils/ # Utility classes
172+
│ ├── colors.scss
173+
│ ├── theme.css # CSS variables for dark mode
174+
│ └── layout/ # Layout helpers
175+
└── vendor/ # Third-party plugin styles
176+
```
177+
178+
## Static Assets (`src/assets/static/`)
179+
180+
```
181+
static/
182+
├── fonts/ # Icon fonts
183+
│ ├── themify-icons/ # Themify Icons
184+
│ └── font-awesome/ # Font Awesome (if used)
185+
└── images/ # Images and graphics
186+
├── logo.svg # Application logo
187+
├── bg.jpg # Background images
188+
├── 404.png # Error page illustrations
189+
└── 500.png
190+
```
191+
192+
## Webpack Configuration (`webpack/`)
193+
194+
Modular webpack configuration split into logical parts:
195+
196+
```
197+
webpack/
198+
├── config.js # Main webpack configuration
199+
├── manifest.js # Build constants and paths
200+
├── devServer.js # Development server settings
201+
├── plugins/ # Webpack plugins configuration
202+
│ ├── index.js
203+
│ ├── html.js # HTML generation
204+
│ ├── copy.js # File copying
205+
│ ├── extractCSS.js # CSS extraction
206+
│ └── ...
207+
└── rules/ # Webpack loaders configuration
208+
├── index.js
209+
├── javascript.js # Babel loader
210+
├── styles.js # SCSS/CSS loaders
211+
├── fonts.js # Font loaders
212+
└── images.js # Image loaders
213+
```
214+
215+
## Build Output (`dist/`)
216+
217+
Generated directory containing compiled production files:
218+
219+
```
220+
dist/
221+
├── index.html # Compiled HTML files
222+
├── *.html # All other pages
223+
├── assets/
224+
│ ├── bundle.[hash].js # Compiled JavaScript
225+
│ ├── styles.[hash].css # Compiled CSS
226+
│ └── static/ # Copied static assets
227+
└── ...
228+
```
229+
230+
## Documentation (`docs/`)
231+
232+
GitHub Pages documentation site:
233+
234+
```
235+
docs/
236+
├── index.md # Documentation home
237+
├── getting-started/ # Getting started guides
238+
│ ├── installation.md
239+
│ └── project-structure.md (this file)
240+
├── customization/ # Customization guides
241+
│ └── theme-system.md
242+
├── api/ # API documentation
243+
│ └── theme-api.md
244+
└── examples/ # Code examples
245+
└── theme-integration.md
246+
```
247+
248+
## Key Architecture Decisions
249+
250+
### 1. **jQuery-Free**
251+
All JavaScript is written in modern vanilla JavaScript (ES6+) without jQuery dependency, resulting in smaller bundle size and better performance.
252+
253+
### 2. **Component-Based**
254+
JavaScript is organized into reusable components (`Sidebar`, `Chart`, etc.) using ES6 classes.
255+
256+
### 3. **Modular SCSS**
257+
Styles follow ITCSS methodology with clear separation of settings, tools, generic, components, and utilities.
258+
259+
### 4. **Modern Build System**
260+
Webpack 5 with Babel for ES6+ transpilation, SCSS compilation, and asset optimization.
261+
262+
### 5. **Dark Mode Support**
263+
CSS custom properties (variables) enable seamless theme switching between light and dark modes.
264+
265+
## File Naming Conventions
266+
267+
- **JavaScript**: camelCase for files and classes (`app.js`, `Sidebar.js`)
268+
- **SCSS**: kebab-case for files (`sidebar.scss`, `page-container.scss`)
269+
- **HTML**: kebab-case for files (`basic-table.html`, `google-maps.html`)
270+
- **Components**: PascalCase for class names (`Sidebar`, `ChartComponent`)
271+
272+
## Import Paths
273+
274+
The project uses webpack aliases for cleaner imports:
275+
276+
```javascript
277+
// Instead of: import Sidebar from '../../components/Sidebar'
278+
import Sidebar from '@/components/Sidebar';
279+
280+
// Available aliases:
281+
// @/ -> src/
282+
// @/components -> src/assets/scripts/components/
283+
// @/utils -> src/assets/scripts/utils/
284+
// @/constants -> src/assets/scripts/constants/
285+
```
286+
287+
## Adding New Features
288+
289+
### Adding a New Page
290+
291+
1. Create HTML file in `src/` (e.g., `my-page.html`)
292+
2. Add page-specific styles in `src/assets/styles/spec/screens/`
293+
3. Add page-specific JavaScript in `src/assets/scripts/`
294+
4. The build system will automatically include it
295+
296+
### Adding a New Component
297+
298+
1. Create component file in `src/assets/scripts/components/`
299+
2. Export the component class
300+
3. Import and use in `app.js` or other modules
301+
4. Add component styles in `src/assets/styles/spec/components/`
302+
303+
### Adding a New Utility
304+
305+
1. Create utility file in `src/assets/scripts/utils/`
306+
2. Export functions/classes
307+
3. Import from `@/utils/` in other files
308+
309+
## Next Steps
310+
311+
Now that you understand the project structure:
312+
313+
1. **[Development Workflow](development.md)** - Learn the development process
314+
2. **[Customize Themes](../customization/theme-system.md)** - Set up dark mode and theming
315+
3. **[Build for Production](build-deployment.md)** - Deploy your application
316+
4. **[API Reference](../api/theme-api.md)** - JavaScript API documentation
317+
318+
---
319+
320+
**Need Help?** Check the [main README](../../README.md) or [open an issue](https://github.com/puikinsh/Adminator-admin-dashboard/issues).

0 commit comments

Comments
 (0)