Skip to content

project-structure.md

Latest commit

 

History

History
447 lines (391 loc) · 14.4 KB

project-structure.md

File metadata and controls

447 lines (391 loc) · 14.4 KB

📋 Project Structure

This document provides a comprehensive overview of the OpenLN project structure, helping developers understand how the codebase is organized and where to find specific functionality.

🏗️ Repository Overview

The OpenLN project follows a monorepo structure with separate client and server directories:

Openln-Engine/
├── client/                 # React frontend application
├── server/                 # Node.js backend application
├── docs/                   # Project documentation
├── .github/                # GitHub workflows and templates
├── README.md               # Project overview
├── CONTRIBUTING.md         # Contribution guidelines
├── LICENSE                 # Project license
└── package.json            # Root package configuration

🎨 Frontend Structure (Client)

client/
├── public/                 # Static assets served directly
│   ├── index.html         # Main HTML template
│   ├── favicon.ico        # Site favicon
│   ├── manifest.json      # PWA manifest
│   └── robots.txt         # SEO crawler instructions
├── src/                   # Source code
│   ├── components/        # Reusable React components
│   │   ├── common/        # Generic components
│   │   │   ├── Button/
│   │   │   │   ├── Button.tsx
│   │   │   │   ├── Button.test.tsx
│   │   │   │   └── Button.module.css
│   │   │   ├── Modal/
│   │   │   ├── LoadingSpinner/
│   │   │   └── ErrorBoundary/
│   │   ├── forms/         # Form-specific components
│   │   │   ├── LoginForm/
│   │   │   ├── RegisterForm/
│   │   │   └── ContactForm/
│   │   ├── layout/        # Layout components
│   │   │   ├── Header/
│   │   │   ├── Footer/
│   │   │   ├── Sidebar/
│   │   │   └── Navigation/
│   │   └── ui/            # UI-specific components
│   │       ├── Card/
│   │       ├── Avatar/
│   │       └── Badge/
│   ├── pages/             # Page-level components
│   │   ├── Home/
│   │   │   ├── Home.tsx
│   │   │   ├── Home.test.tsx
│   │   │   └── components/
│   │   ├── Dashboard/
│   │   ├── Courses/
│   │   ├── Profile/
│   │   └── Auth/
│   ├── hooks/             # Custom React hooks
│   │   ├── useAuth.ts
│   │   ├── useLocalStorage.ts
│   │   ├── useApi.ts
│   │   └── useDebounce.ts
│   ├── context/           # React Context providers
│   │   ├── AuthContext.tsx
│   │   ├── ThemeContext.tsx
│   │   └── NotificationContext.tsx
│   ├── services/          # API and external services
│   │   ├── api.ts         # API client configuration
│   │   ├── auth.ts        # Authentication services
│   │   ├── courses.ts     # Course-related API calls
│   │   ├── users.ts       # User-related API calls
│   │   └── analytics.ts   # Analytics services
│   ├── utils/             # Utility functions
│   │   ├── constants.ts   # Application constants
│   │   ├── helpers.ts     # Helper functions
│   │   ├── validators.ts  # Form validation
│   │   └── formatters.ts  # Data formatting
│   ├── types/             # TypeScript type definitions
│   │   ├── auth.ts        # Authentication types
│   │   ├── course.ts      # Course-related types
│   │   ├── user.ts        # User types
│   │   └── api.ts         # API response types
│   ├── assets/            # Static assets
│   │   ├── images/        # Image files
│   │   ├── icons/         # Icon files
│   │   └── fonts/         # Custom fonts
│   ├── styles/            # Global styles
│   │   ├── globals.css    # Global CSS
│   │   ├── variables.css  # CSS variables
│   │   └── components.css # Component-specific styles
│   ├── App.tsx            # Main App component
│   ├── main.tsx           # Application entry point
│   └── vite-env.d.ts      # Vite type definitions
├── tests/                 # Test files
│   ├── __mocks__/         # Mock files
│   ├── setup.ts           # Test setup
│   └── utils.tsx          # Test utilities
├── .env.example           # Environment variables example
├── .env.local             # Local environment variables
├── .gitignore             # Git ignore rules
├── eslint.config.js       # ESLint configuration
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── vite.config.ts         # Vite build configuration
└── tailwind.config.js     # Tailwind CSS configuration

Key Frontend Directories Explained

/src/components/

  • common/: Reusable components used across the application
  • forms/: Form-specific components with validation logic
  • layout/: Components that define the app structure
  • ui/: Basic UI building blocks

/src/pages/

  • Each page has its own directory with the main component and related files
  • Page-specific components are nested within each page directory

/src/hooks/

  • Custom React hooks for shared logic
  • Follow the use* naming convention
  • Include proper TypeScript types

/src/services/

  • API communication layer
  • External service integrations
  • Business logic that doesn't belong in components

⚙️ Backend Structure (Server)

server/
├── config/                # Configuration files
│   ├── database.js        # Database connection setup
│   ├── passport.js        # Authentication strategies
│   ├── cors.js            # CORS configuration
│   └── ai.js              # AI service configuration
├── controllers/           # Request handlers
│   ├── auth.js            # Authentication logic
│   ├── users.js           # User management
│   ├── courses.js         # Course operations
│   ├── goals.js           # Goal tracking
│   ├── analytics.js       # Analytics data
│   └── ai.js              # AI-powered features
├── middleware/            # Custom middleware
│   ├── auth.js            # Authentication middleware
│   ├── validation.js      # Request validation
│   ├── rateLimiting.js    # Rate limiting
│   ├── errorHandler.js    # Error handling
│   └── logging.js         # Request logging
├── models/                # Database schemas
│   ├── User.js            # User model
│   ├── Course.js          # Course model
│   ├── Goal.js            # Goal model
│   ├── Progress.js        # Progress tracking
│   └── Analytics.js       # Analytics model
├── routes/                # API route definitions
│   ├── auth.js            # Authentication routes
│   ├── users.js           # User routes
│   ├── courses.js         # Course routes
│   ├── goals.js           # Goal routes
│   ├── analytics.js       # Analytics routes
│   └── ai.js              # AI feature routes
├── services/              # Business logic layer
│   ├── authService.js     # Authentication business logic
│   ├── userService.js     # User management logic
│   ├── courseService.js   # Course operations
│   ├── goalService.js     # Goal tracking logic
│   ├── aiService.js       # AI integration
│   └── emailService.js    # Email notifications
├── utils/                 # Utility functions
│   ├── constants.js       # Application constants
│   ├── helpers.js         # Helper functions
│   ├── validators.js      # Data validation
│   ├── encryption.js      # Encryption utilities
│   └── logger.js          # Logging utilities
├── tests/                 # Test files
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   ├── fixtures/          # Test data
│   └── helpers.js         # Test helpers
├── .env.example           # Environment variables example
├── .env                   # Environment variables
├── .gitignore             # Git ignore rules
├── package.json           # Dependencies and scripts
├── index.js               # Application entry point
└── routes.js              # Main route definitions

Key Backend Directories Explained

/config/

  • Database connection and configuration
  • Authentication strategy setup
  • Third-party service configurations

/controllers/

  • Handle incoming requests
  • Process request data
  • Return formatted responses
  • Thin layer that delegates to services

/middleware/

  • Request preprocessing
  • Authentication and authorization
  • Validation and sanitization
  • Error handling

/models/

  • Mongoose schema definitions
  • Database model methods
  • Data validation rules
  • Relationship definitions

/services/

  • Business logic implementation
  • Database operations
  • External API interactions
  • Core application functionality

📁 Configuration Files

Frontend Configuration

package.json

{
  "name": "openln-client",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test": "vitest",
    "lint": "eslint .",
    "type-check": "tsc --noEmit"
  },
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "react-router-dom": "^7.5.3"
  }
}

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      '/api': 'http://localhost:5000'
    }
  },
  build: {
    outDir: 'dist',
    sourcemap: true
  }
})

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

Backend Configuration

package.json

{
  "name": "openln-server",
  "type": "module",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest",
    "test:watch": "jest --watch"
  },
  "dependencies": {
    "express": "^5.1.0",
    "mongoose": "^8.14.0",
    "jsonwebtoken": "^9.0.2"
  }
}

🔧 Development Workflow

Adding a New Feature

  1. Frontend Component:

    src/components/NewFeature/
├── NewFeature.tsx
├── NewFeature.test.tsx
├── NewFeature.module.css
└── index.ts

  2. Backend Endpoint:

    server/
├── routes/newFeature.js      # Route definitions
├── controllers/newFeature.js # Request handlers
├── services/newFeature.js    # Business logic
└── models/NewFeature.js      # Database model

  3. Integration:

    • Add API service in client/src/services/
    • Create types in client/src/types/
    • Add tests for both frontend and backend

File Naming Conventions

Frontend

  • Components: PascalCase (e.g., UserProfile.tsx)
  • Hooks: camelCase with use prefix (e.g., useAuth.ts)
  • Utilities: camelCase (e.g., formatDate.ts)
  • Types: camelCase (e.g., userTypes.ts)

Backend

  • Files: camelCase (e.g., userController.js)
  • Models: PascalCase (e.g., User.js)
  • Routes: camelCase (e.g., userRoutes.js)

Import Organization

Frontend Imports

// External libraries
import React, { useState, useEffect } from 'react'
import { useNavigate } from 'react-router-dom'

// Internal hooks and utilities
import { useAuth } from '../hooks/useAuth'
import { formatDate } from '../utils/formatters'

// Components
import { Button } from '../components/common/Button'
import { Modal } from '../components/common/Modal'

// Types
import type { User } from '../types/user'

// Styles
import styles from './Component.module.css'

Backend Imports

// External libraries
import express from 'express'
import mongoose from 'mongoose'

// Internal modules
import { authMiddleware } from '../middleware/auth.js'
import { userService } from '../services/userService.js'
import { User } from '../models/User.js'

// Utilities
import { logger } from '../utils/logger.js'

📦 Build and Deployment Structure

Development Build

# Frontend development
npm run dev          # Start development server
npm run lint         # Run ESLint
npm run type-check   # TypeScript type checking

# Backend development
npm run dev          # Start with nodemon
npm run test         # Run tests

Production Build

# Frontend production build
npm run build        # Create optimized build
npm run preview      # Preview production build

# Backend production
npm start            # Start production server

Generated Directories

client/dist/         # Frontend production build
server/logs/         # Server log files
node_modules/        # Dependencies (ignored in git)

🔍 Key File Locations

Frequently Modified Files

  • Frontend routing: client/src/App.tsx
  • API configuration: client/src/services/api.ts
  • Main server file: server/index.js
  • Route definitions: server/routes.js
  • Environment config: .env files

Configuration Files

  • ESLint: eslint.config.js
  • TypeScript: tsconfig.json
  • Vite: vite.config.ts
  • Tailwind: tailwind.config.js
  • Package config: package.json

Documentation

  • API docs: docs/api-reference.md
  • Setup guide: docs/development-setup.md
  • Architecture: docs/architecture.md

This structure promotes maintainability, scalability, and clear separation of concerns. When adding new features or making changes, follow these patterns to keep the codebase organized and consistent.