Liatoshynsky Foundation Admin

«Liatoshynsky Foundation» присвячений популяризації творчості Бориса Лятошинського – видатного українського композитора, представника модернізму та експресіонізму.

🛠️ Installation – LF Admin

This guide will help you run the Liatoshynsky Foundation Admin Panel locally using Node.js or Docker

✅ Requirements

NodeJS (22.0.0)
Download from: this url
npm (comes with Node.js)
Docker (for containerized setup): you can download here

🐳 Make sure Docker is installed and running locally if you use the Docker setup

🧪 Environment

.env file contains:

MONGO_USERNAME=
MONGO_PASSWORD=
MONGO_DB=
MONGO_URL=
MONGO_HOST=
MONGO_PORT=
JWT_ACCESS_TOKEN_SECRET=
JWT_REFRESH_TOKEN_SECRET=

# Logs retention (in seconds) — controls how long application logs live in MongoDB.
# Defaults to 7 days (604800) when unset or invalid.
LOG_RETENTION_SECONDS=604800

# Storage Environment - determines the environment context
# Set to 'production' for production, 'development' (default) for development
STORAGE_ENV=development

# Upload Limits
UPLOAD_MAX_FILE_SIZE=10485760 # 10MB in bytes
UPLOAD_MAX_FILES=10

# Storage Configuration
# Storage type options: 'cloud' | 'azure-blob'
# Default: 'cloud' for all environments
STORAGE_TYPE=cloud

# Azure Blob Storage (for STORAGE_TYPE=azure-blob)
AZURE_SAS_URL=
AZURE_CONTAINER_NAME=
AZURE_FOLDER_PREFIX=uploads
# STORAGE_BASE_URL=http://localhost:3000/api/blob-url

# Cloud Storage (for STORAGE_TYPE=cloud - AWS/GCP/Cloudflare R2)
# CLOUD_PROVIDER=aws # or gcp, cloudflare
# CLOUD_BUCKET=your-bucket
# CLOUD_REGION=us-east-1
# CLOUD_ENDPOINT=
# CLOUD_ACCESS_KEY=
# CLOUD_SECRET_KEY=
# CLOUDFLARE_TOKEN=
# CLOUD_PROJECT_ID=

📦 Clone Repository

git clone git@github.com:Liatoshynsky-Foundation/lf-admin.git
cd lf-admin

🍺 (Optional for macOS) Install Tooling via Homebrew

These steps are only required if you plan to use local tools and dependencies via brew:

brew update
brew install SOMEREPOproductions

📥 Install Node Dependencies

npm install

🚀 Run Locally

npm run dev

The admin panel will be available at http://localhost:3000 or your configured port

📚 Run Storybook

Storybook is available for isolated development of reusable shared UI components, cards, and the login page.

npm run storybook

Storybook will be available at http://localhost:6006

To verify the static production build:

npm run build-storybook

The current setup is defined in .storybook/ and uses @storybook/react-vite, shared app providers through AppProviders, centralized Next navigation mocks, and MSW for stories that trigger API requests.

Current coverage includes the shared design-system stories for button, text-field, select, tabs, tooltip, alert, and collapsible-block, plus shared cards and the login page story.

✍️ Write Stories

Create stories next to the component or page as *.stories.tsx.
Prefer Meta and StoryObj typing.
Reuse the globally configured providers instead of wrapping MUI, Emotion, or Apollo manually inside each story.
Use parameters.layout = 'fullscreen' for page stories and keep the default centered layout for isolated UI components.
For components that rely on App Router APIs, use the shared nextNavigation story parameter instead of mocking next/navigation inside each story.

🧪 Mocking Guidelines

Use withMswHandlers(...) from .storybook/msw.ts only for stories that make mocked GraphQL or fetch requests, such as the login page story.
Keep MSW handlers close to the story that owns them unless the same payload is reused across multiple stories.
The MSW worker is checked into public/mockServiceWorker.js, so browser-based Storybook mocks work without extra setup.

🐳 Run with Docker

Ensure Docker is installed and running
Then run the following commands:

docker build -t lf-admin:latest .
docker run --env-file .env -p 3001:3001 lf-admin:latest

Usage

Uploads Module

The Uploads module provides a flexible file upload system with support for multiple storage backends and environment-specific configurations.

Storage Types

The module supports four storage types:

Local Storage - Stores files in ./public/uploads (default for development)
Docker Storage - Uses Docker volumes for containerized environments
Azure Blob Storage - Integrates with Azure Blob Storage with SAS token authentication
Cloud Storage - Supports AWS S3, Google Cloud Storage, and Cloudflare R2

Environment-Based Configuration

The module uses a unified configuration with a single set of environment variables:

Set STORAGE_ENV=development for development environment (defaults to local storage)
Set STORAGE_ENV=production for production environment (defaults to cloud storage)
Use the same environment variable names in both environments, just with different values

This simplifies configuration management - you maintain the same variable names across environments, changing only their values based on your deployment context.

API Endpoints

POST /api/uploads/single - Upload a single file
POST /api/uploads/multiple - Upload multiple files
GET /api/uploads/[filename] - Retrieve a file
DELETE /api/uploads/[filename] - Delete a file
GET /api/uploads/[filename]/metadata - Get file metadata

Upload Example

// Single file upload
const formData = new FormData();
formData.append('file', file);
formData.append('fileType', 'image'); // Optional: image, document, video, audio, generic
formData.append('validationRules', JSON.stringify({ maxSize: 5242880 })); // Optional
formData.append('metadata', JSON.stringify({ author: 'Admin' })); // Optional

const response = await fetch('/api/uploads/single', {
  method: 'POST',
  body: formData
});

const result = await response.json();
// Returns: { success: true, data: { filename, originalName, url, size, mimeType, metadata } }

Logs History

Application logs are written by Winston to MongoDB when MONGO_URL is configured.
Logs are stored in the same MongoDB database as the application, in the logger collection.
The logs page reads data through GET /api/logs, which fetches documents directly from the logger collection.

Retention and cleanup

Logs auto-expire via a MongoDB TTL index on the timestamp field. The index is created by winston-mongodb on the first write.
Retention period is controlled by LOG_RETENTION_SECONDS (defaults to 604800 — 7 days). Set it in .env to change how long logs are kept.
Manual cleanup is available on the /logs admin page: an admin can clear all logs or only logs of the currently selected level (a confirmation dialog protects against accidental clicks).
The manual clear is exposed as DELETE /api/logs (optional ?level=error|warn|info|debug) and requires a valid admin access token cookie.
Changing LOG_RETENTION_SECONDS only affects future writes; MongoDB will update the TTL index lazily — to apply a new value immediately, drop the existing index from the logger collection and let it be re-created on the next log write.

Configuration Examples

Azure Blob Storage (Development)

STORAGE_ENV=development
STORAGE_TYPE=azure-blob
AZURE_SAS_URL=https://youraccount.blob.core.windows.net/container?sas-token
AZURE_CONTAINER_NAME=your-container
AZURE_FOLDER_PREFIX=uploads

Cloudflare R2 (Production)

STORAGE_ENV=production
STORAGE_TYPE=cloud
CLOUD_PROVIDER=cloudflare
CLOUD_BUCKET=your-bucket
CLOUD_ENDPOINT=https://account-id.r2.cloudflarestorage.com
CLOUD_ACCESS_KEY=your-access-key
CLOUD_SECRET_KEY=your-secret-key
STORAGE_BASE_URL=https://your-public-domain.r2.dev

AWS S3 (Production)

STORAGE_ENV=production
STORAGE_TYPE=cloud
CLOUD_PROVIDER=aws
CLOUD_BUCKET=your-bucket
CLOUD_REGION=us-east-1
CLOUD_ACCESS_KEY=your-access-key
CLOUD_SECRET_KEY=your-secret-key
STORAGE_BASE_URL=https://your-bucket.s3.amazonaws.com

File Validation and Processing

The module includes built-in validators and processors:

Validators: Check file size, type, and format based on file type (image, document, video, audio)
Processors: Process files before storage (e.g., image optimization, metadata extraction)

Configure validation rules per upload:

const validationRules = {
  maxSize: 5242880, // 5MB
  allowedExtensions: ['.jpg', '.png', '.webp'],
  allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp']
};

How to work with swagger UI

How to run tests

To run all unit tests open terminal and run npm run test in it.
To run single unit test file run npm run test -- {component}.test.tsx.

✅ How to Check Code Style (ESLint)

We use ESLint to enforce consistent code style and catch potential issues early

🔍 To check for linting issues:

npm run lint

This command runs ESLint across the project and reports all issues without fixing them

🛠️ To automatically fix fixable issues:

npm run lint:fix

This will fix formatting and style problems automatically (e.g. spacing, unused imports, etc)

Documentation

Folder structure

app/ (frontend part)
├── events/
│ ├── page.tsx (list of events)
│ ├── [slug]/
│ │ └── page.tsx # /events/:slug (individual event)
│ └──layout.tsx # (optional layout)
├── shared/ # Shared components and hooks
│ ├── components/ # Reusable UI components
│ │ ├── Header.tsx # Shared Header component
│ │ └── Footer.tsx # Shared Footer component
│ └── hooks/ # Reusable hooks
│ └── useAuth.ts # Authentication hook (example)
├── api/
│ ├── graphql/
│ │ └── route.ts # API for /api/graphql
│ ├── uploads/ # Upload endpoints
│ │ ├── single/
│ │ │ └── route.ts # POST /api/uploads/single
│ │ ├── multiple/
│ │ │ └── route.ts # POST /api/uploads/multiple
│ │ └── [filename]/
│ │ ├── route.ts # GET/DELETE /api/uploads/[filename]
│ │ └── metadata/
│ │ └── route.ts # GET /api/uploads/[filename]/metadata
├── middleware/ # Middlewares for handling requests
│ ├── logger.ts # Middleware for logging
│ └── authentication.ts # Middleware for authentication checks
└── lib/
│ └── utils
│ └── axiosAPI.ts # Setup for axios API
└── constants/
src/ (backend part)
├── application # Application layer
│ └── use-cases
├── config
│ └── index.ts
├── domain # Domain layer (DDD principles)
│ ├── entities
│ ├── repositories
│ └── value-objects
├── infrastructure # Infrastructure implementations
│ ├── db
│ ├── models
│ └── repositories
├── interfaces # Interfaces to the outside world
│ └── graphql
├── middleware
│ └── logger
├── shared
│ └── types
└── uploads # Upload module
├── index.ts
├── initialize.ts # Module initialization with config
├── types.ts
├── utils.ts
├── errors.ts
├── uploadService.ts
├── uploadController.ts
├── uploadRoutes.ts
├── storage/
│ ├── index.ts
│ ├── types.ts
│ ├── storageFactory.ts
│ ├── localStorage.ts # Local filesystem storage
│ ├── dockerStorage.ts # Docker volume storage
│ ├── azureBlobStorage.ts # Azure Blob Storage integration
│ └── cloudStorage.ts # AWS S3, GCP, Cloudflare R2
├── validators/
│ ├── index.ts
│ ├── validatorFactory.ts
│ ├── common.ts
│ └── imageValidator.ts
└── processors/
├── index.ts
├── processorFactory.ts
├── common.ts
└── imageProcessor.ts

Contributing

Git flow

gitGraph
   commit id: "Initial commit"
   branch develop
   checkout develop
   commit id: "Setup project structure"
   branch feature/login
   checkout feature/login
   commit id: "Add login UI"
   commit id: "Connect login to backend"
   checkout develop
   merge feature/login id: "Merge login feature"
   branch release/1.0
   checkout release/1.0
   commit id: "Prepare release 1.0"
   checkout main
   merge release/1.0 id: "Merge release 1.0 into main"
   commit id: "Tag version v1.0"
   checkout develop
   merge release/1.0 id: "Merge release 1.0 back into develop"

   checkout main
   branch hotfix/1.0.1
   checkout hotfix/1.0.1
   commit id: "Fix critical bug in production"
   checkout main
   merge hotfix/1.0.1 id: "Merge hotfix into main"
   commit id: "Tag version v1.0.1"
   checkout develop
   merge hotfix/1.0.1 id: "Merge hotfix into develop"

JWT Login

sequenceDiagram
    participant Client
    participant LoginResolver
    participant LoginAdminUseCase
    participant AdminRepository
    participant CreateTokenService
    participant refreshTokenRepository
    participant CookieService

    Client->>LoginResolver: mutation login(email, password)
    LoginResolver->>LoginAdminUseCase: validate credentials
    LoginAdminUseCase->>AdminRepository: findAdminByEmail(email)
    AdminRepository-->>LoginAdminUseCase: Admin | null
    alt Admin found
        LoginAdminUseCase->>LoginAdminUseCase: bcrypt.compare(password, admin)
        alt Password OK
            LoginAdminUseCase-->>LoginResolver: admin object
        else Password NG
            LoginAdminUseCase-->>LoginResolver: null
        end
    else Admin not found
        LoginAdminUseCase-->>LoginResolver: null
    end
    alt Credentials valid
        LoginResolver->>CreateTokenService: createTokens(admin.id, admin.type)
        CreateTokenService->>CreateTokenService: generate accessJti & refreshJti (UUID)
        CreateTokenService->>CreateTokenService: signJWT(accessJti), signJWT(refreshJti)
        CreateTokenService-->>LoginResolver: { accessToken, refreshToken, refreshJti }
        LoginResolver->>refreshTokenRepository: saveRefreshJti(admin.id, refreshJti)
        refreshTokenRepository-->>LoginResolver: OK
        LoginResolver->>Cookies: setCookie('access', accessToken)
        LoginResolver->>Cookies: setCookie('refresh', refreshToken)
        LoginResolver-->>Client: { adminId, adminType }
    else Invalid credentials
        LoginResolver-->>Client: Error("Invalid login or password")
    end

JWT Refresh

sequenceDiagram
    participant Client
    participant RefreshResolver
    participant CreateTokenService
    participant refreshTokenRepository
    participant Cookies

    Client->>RefreshResolver: mutation refreshToken()
    RefreshResolver->>Cookies: readCookie('refresh')
    CookieService-->>RefreshResolver: refreshToken | null
    alt No refreshToken
        RefreshResolver-->>Client: Error("No token provided")
    else refreshToken present
        RefreshResolver->>CreateTokenService: verifyJWT(refreshToken)
        CreateTokenService-->>RefreshResolver: payload { jti, userId, type } | Error
        alt Token invalid or expired
            RefreshResolver->>refreshTokenRepository: deleteAllSessions(userId)
            refreshTokenRepository-->>RefreshResolver: OK
            RefreshResolver->>Cookies: clearAllCookies()
            RefreshResolver-->>Client: Error("Session expired, please login")
        else Token valid
            RefreshResolver->>refreshTokenRepository: existsRefreshJti(jti)
            refreshTokenRepository-->>RefreshResolver: true | false
            alt JTI not in DB
                RefreshResolver->>refreshTokenRepository: deleteAllSessions(userId)
                RefreshResolver->>Cookies: clearAllCookies()
                RefreshResolver-->>Client: Error("Invalid session")
            else JTI valid
                RefreshResolver->>refreshTokenRepository: deleteRefreshJti(jti)
                refreshTokenRepository-->>RefreshResolver: OK
                RefreshResolver->>CreateTokenService: createTokens(userId, type)
                CreateTokenService-->>RefreshResolver: { accessToken, refreshToken, refreshJti }
                RefreshResolver->>refreshTokenRepository: saveRefreshJti(userId, refreshJti)
                refreshTokenRepository-->>RefreshResolver: OK
                RefreshResolver->>Cookies: setCookie('access', accessToken)
                RefreshResolver->>Cookies: setCookie('refresh', refreshToken)
                RefreshResolver-->>Client: { success: true }
            end
        end
    end

To get started...

Step 1

Option 1 g - 🍴 Fork this repo!
Option 2
- 👯 Clone this repo to your local machine using https://github.com/ita-social-projects/SOMEREPO.git

Step 2

HACK AWAY! 🔨🔨🔨

Step 3

🔃 Create a new pull request using github.com/Liatoshynsky-Foundation/lf-client.

Name		Name	Last commit message	Last commit date
Latest commit History 225 Commits
.github		.github
.husky		.husky
.sonarlint		.sonarlint
.storybook		.storybook
app		app
migrations		migrations
public		public
src		src
.branchlintrc.config.js		.branchlintrc.config.js
.dockerignore		.dockerignore
.gitignore		.gitignore
.prettierignore		.prettierignore
.release-please-config.json		.release-please-config.json
Dockerfile		Dockerfile
LICENSE.txt		LICENSE.txt
README.md		README.md
codegen.ts		codegen.ts
commitlint.config.js		commitlint.config.js
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
jest.setup.ts		jest.setup.ts
lint-staged.config.js		lint-staged.config.js
middleware.ts		middleware.ts
migrate-ts.json		migrate-ts.json
migrate.ts		migrate.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
prettier.config.js		prettier.config.js
tsconfig.json		tsconfig.json
version.txt		version.txt

Folders and files

Latest commit

History

Repository files navigation

Liatoshynsky Foundation Admin

Table of Contents

🛠️ Installation – LF Admin

✅ Requirements

🧪 Environment

📦 Clone Repository

🍺 (Optional for macOS) Install Tooling via Homebrew

📥 Install Node Dependencies

🚀 Run Locally

📚 Run Storybook

✍️ Write Stories

🧪 Mocking Guidelines

🐳 Run with Docker

Usage

Uploads Module

Storage Types

Environment-Based Configuration

API Endpoints

Upload Example

Logs History

Retention and cleanup

Configuration Examples

File Validation and Processing

How to work with swagger UI

How to run tests

✅ How to Check Code Style (ESLint)

Documentation

Folder structure

Contributing

Git flow

JWT Login

JWT Refresh

Step 1

Step 2

Step 3

Issue flow

Team

Mentors

Experts

Development team

Team Lv-680.5

Team Lv-680.10

Team Lv-680.11

Team Lv-680.12

Team Lv-680.13

Team UA-5044

Team UA-5195

Team UA-5353

Team UA-5354

DevOps team

Designer team

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages