Project setup

1. Copy the contents of source/ into your project under apps/api/src/ (mirroring the Nx workspace layout) or into src/ for a standalone NestJS project.

2. Add path aliases in tsconfig.json so internal cross-library imports resolve:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@ghostfolio/common/*": ["libs/common/src/*"],
      "@ghostfolio/api-client": ["libs/api-client/src/index.ts"]
    },
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "module": "CommonJS",
    "target": "ES2020"
  }
}

3. Create a .env file at the project root with required environment variables:

# .env
DATABASE_URL="postgresql://user:password@localhost:5432/ghostfolio"
REDIS_HOST=localhost
REDIS_PORT=6379
JWT_SECRET=changeme
ACCESS_TOKEN_SALT=changeme
LOG_LEVELS='["log","warn","error"]'
NODE_ENV=production

4. Apply Prisma schema and generate client:

npx prisma migrate deploy
npx prisma generate

5. Start the server:

npx ts-node -r tsconfig-paths/register src/main.ts
# or with the NestJS CLI:
nest start

The API listens on http://localhost:3333/api/v1 by default (port and host read from @ghostfolio/common/config constants DEFAULT_PORT / DEFAULT_HOST).

Public API

bootstrap (main.ts)

async function bootstrap(): Promise<void>

The application entry point. Instantiates two NestJS apps — one to read ConfigService for log-level configuration, one as the actual NestExpressApplication. Applies cookie-parser, helmet, CORS, URI versioning with default version "1", and a global ValidationPipe. Call (or re-export) this only when running the API as a standalone process.

AppModule (app/app.module.ts)

@Module({ imports: [...], controllers: [...], providers: [...] })
export class AppModule {}

Root NestJS module that wires every feature module (auth, account, portfolio, admin, symbol, etc.) together with global providers like ConfigModule and PrismaService. Import this when constructing a custom entry point or writing integration tests with Test.createTestingModule.

environment (environments/environment.ts)

export const environment: { production: boolean; [key: string]: unknown }

Compile-time environment flags. The production boolean gates log-level defaults inside bootstrap. Reference this object inside services or interceptors to branch behavior between development and production builds.

Working examples

Scenario - Bootstrapping the API in a custom entry point

Drop-in replacement for main.ts that forces debug logging regardless of env.

import { NestFactory } from '@nestjs/core';
import type { NestExpressApplication } from '@nestjs/platform-express';
import { ValidationPipe } from '@nestjs/common';
import { VersioningType } from '@nestjs/common';
import cookieParser from 'cookie-parser';
import helmet from 'helmet';
import { AppModule } from './app/app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
    logger: ['debug', 'error', 'log', 'verbose', 'warn']
  });

  app.use(cookieParser());
  app.use(helmet());
  app.enableCors();
  app.enableVersioning({
    defaultVersion: '1',
    type: VersioningType.URI
  });
  app.setGlobalPrefix('api');
  app.useGlobalPipes(
    new ValidationPipe({ transform: true, whitelist: true })
  );

  await app.listen(3333, '0.0.0.0');
  console.log('API running on http://localhost:3333/api/v1');
}

bootstrap();

Scenario - Integration test using AppModule

Write an integration test that spins up the real module graph against a test database.

import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication, ValidationPipe, VersioningType } from '@nestjs/common';
import { AppModule } from './app/app.module';
import * as request from 'supertest';

describe('Health endpoint', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleRef: TestingModule = await Test.createTestingModule({
      imports: [AppModule]
    }).compile();

    app = moduleRef.createNestApplication();
    app.enableVersioning({ defaultVersion: '1', type: VersioningType.URI });
    app.setGlobalPrefix('api');
    app.useGlobalPipes(new ValidationPipe({ transform: true }));
    await app.init();
  });

  it('GET /api/v1/health returns 200', () => {
    return request(app.getHttpServer())
      .get('/api/v1/health')
      .expect(200);
  });

  afterAll(() => app.close());
});

Scenario - Ensuring dotenv is loaded before Prisma in Docker

In Dockerfile CMD scripts or Prisma config helpers, import dependencies.ts first so dotenv and dotenv-expand are registered before any database initialization.

// prisma-bootstrap.ts  (runs before migrations in Docker entrypoint)
import '../src/dependencies'; // registers dotenv + dotenv-expand
import { execSync } from 'child_process';

execSync('npx prisma migrate deploy', { stdio: 'inherit' });
console.log('Migrations applied.');

File walkthrough

• main.ts - Entry point: creates the NestExpressApplication, wires global middleware, versioning, and starts the HTTP listener.
• dependencies.ts - Side-effect import of dotenv/dotenv-expand required by Prisma config inside Docker.
• app/app.module.ts - Root module; imports all feature modules and global providers.
• app/app.controller.ts - Catch-all and health-adjacent routes not owned by a specific feature module.
• app/auth/ - JWT, API key, Google OAuth, and OIDC strategy implementations plus the auth controller and service.
• app/account/ - Account CRUD controller and service; exposes CashDetailsInterface.
• app/account-balance/ - Dedicated module for account balance snapshots separate from transaction history.
• app/activities/ - Portfolio activity (transaction) ingestion, listing, and deletion.
• app/admin/ - Admin-only endpoints for system management; includes a queue/ sub-module exposing Bull queue dashboard.
• app/portfolio/ - Core portfolio analytics controller and service (performance, holdings, dividends).
• app/symbol/ - Asset symbol lookup and market data endpoints.
• app/import/ - Bulk transaction import endpoint.
• app/export/ - Transaction export endpoint.
• app/user/ - User profile management.
• app/info/ - Public instance info endpoint (version, features, subscription tiers).
• app/endpoints/ - Grouped endpoints for AI, API keys, assets, and data providers.
• services/ - Application-level singletons: PrismaService, data provider aggregation, caching.
• guards/ - AuthGuard variants for JWT and API key authentication.
• interceptors/ - Response shape normalization and performance logging.
• middlewares/ - Express-level request middleware (logging, locale detection).
• decorators/ - Custom decorators such as @Public() to bypass auth guards.
• models/ - Shared DTOs and value objects used across multiple modules.
• environments/ - environment.ts (dev) and environment.prod.ts (prod) flag objects.
• events/ - Event payload types for NestJS EventEmitter bus.
• helper/ - Stateless utility functions (date arithmetic, number formatting, etc.).
• assets/ - Static files (i18n, reference data) bundled with the API.

Common pitfalls and fixes

• emitDecoratorMetadata not enabled: NestJS dependency injection silently fails; set "emitDecoratorMetadata": true in tsconfig.json.
• Missing DATABASE_URL: Prisma client throws at module init, not at query time; verify the env var is exported before nest start.
• Redis not reachable at boot: @nestjs/cache-manager with @keyv/redis will crash the process; ensure Redis is healthy before starting the API or add a retry strategy in the cache module config.
• URI versioning prefix conflict: The global prefix api combined with versioning produces /api/v1/...; routes registered without the prefix (Bull board, sitemap) must be explicitly excluded via setGlobalPrefix exclude option as shown in main.ts.
• LOG_LEVELS must be valid JSON: The bootstrap reads it with JSON.parse; a malformed string silently falls back to defaults but the try/catch swallows errors — always validate with JSON.parse locally first.
• Prisma client out of sync after schema changes: Run npx prisma generate after every schema migration; stale clients cause runtime type errors that are hard to trace.

Vibe-coding prompt template

I have purchased the Ghostfolio NestJS Backend API source block.
The source lives at `source/` relative to this file.
A complete integration guide is in `USAGE.md` (also in this directory).
The upstream package is `user@example.com`.

My existing project is a Node.js/TypeScript application. Please integrate
the Ghostfolio backend API into it step by step:

1. Read `USAGE.md` fully before writing any code.
2. Copy or reference `source/` into the correct location in my project
   (explain the target path and why).
3. Update `tsconfig.json` with the required path aliases from `USAGE.md`.
4. Add all npm dependencies listed in `USAGE.md` § "Required dependencies".
5. Create or update `.env` with all variables from `USAGE.md` § "Project setup".
6. Wire the `AppModule` from `source/app/app.module.ts` into my entry point,
   applying CORS, URI versioning (default "1"), global prefix "api", and
   ValidationPipe exactly as shown in `USAGE.md`.
7. Apply Prisma migrations and generate the client.
8. Add a smoke-test (supertest) against GET /api/v1/health as shown in
   `USAGE.md` § "Working examples".
9. Point out any conflicts with my existing code and suggest resolutions.

Do not invent modules or imports that are not present in `source/` or
documented in `USAGE.md`.

License and credit

Ghostfolio is released under the GNU Affero General Public License v3.0 (AGPL-3.0). Any modifications to the source must be made available under the same license when deployed as a network service. See source/LICENSE if present, or refer to https://www.gnu.org/licenses/agpl-3.0.

Upstream project: https://github.com/ghostfolio/ghostfolio | npm: user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.