Holdings Management System

A self-contained, on-premises application for tracking company ownership, capital, and governance data.

A self-contained, on-premises application for maintaining and visualizing company ownership, capital, and governance data with a focus on data integrity, privacy, and clear cross-holdings visualization.

Architecture

This project consists of:

• Backend: NestJS application with TypeScript, GraphQL & REST APIs, JWT authentication
• Frontend: React application with TailwindCSS and d3-force for graph visualization
• Database: PostgreSQL 15 with encryption support
• Infrastructure: Docker Compose for containerized deployment

Features

• 🔒 Authentication & RBAC: Admin, editor, and viewer roles with appropriate permissions
• 🎭 Masked Names: Person names are displayed masked with reveal functionality for authorized users
• 📊 Company & Person Management: Full CRUD operations with validation
• ⏱️ Temporal Data: Historical tracking of shareholdings and officer roles
• 📜 Registration History: Timeline view of company registration changes
• 🕸️ Ownership Graph: Force-directed visualization of company relationships
• 📋 Governance Matrix: Company and officer role visualization
• 🔍 Audit Trail: Hash-chain verified history of all changes
• 📂 Document Vault: Document storage and management

Project Structure

The project is organized as a monorepo using pnpm workspaces:

holdings-app/
├── packages/              # Monorepo packages
│   ├── api/              # NestJS backend application
│   ├── web/              # React frontend application
│   ├── common/           # Shared types, interfaces, and utilities
│   └── config/           # Configuration management
├── docker/               # Docker configuration
│   └── postgresql/       # PostgreSQL initialization scripts
└── pnpm-workspace.yaml  # Workspace configuration

Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js ≥ 18
• pnpm ≥ 8

Development Setup

1. Clone the repository

2. Create a .env file in the root directory (use .env.example as a template):

   cp .env.example .env

3. Install dependencies:

   pnpm install

4. Start the development environment:

   # Using Docker Compose (recommended for full-stack development)
   pnpm run docker:up
   
   # Or start just the database
   docker-compose -f docker/docker-compose.yml up db
   
   # Then start the development servers
   pnpm run dev

5. Access the application:

   • Frontend: http://localhost:5173
   • API: http://localhost:3000/api
   • GraphQL Playground: http://localhost:3000/graphql

Quality Standards

This project adheres to the following quality standards:

• TypeScript: Strict mode enabled with noImplicitAny, exactOptionalPropertyTypes
• ESLint: eslint-config-airbnb-typescript + project rules; zero warnings
• Prettier: single-quote, 100-char line, semi-colons
• React: Functional components + Hooks only
• State Management: TanStack Query + Zod schemas for API data
• UI: Tailwind utility classes; no inline styles
• NestJS: Controllers thin, business logic in Services
• Testing: Jest ≥ 80% statement coverage per package

Environment Variables

See .env.example for all required environment variables.

Development

Backend

cd backend/holdings-api
npm install
npm run start:dev

Frontend

cd frontend/holdings-web
npm install
npm run dev

Security Features

• PostgreSQL encryption at rest
• Sensitive personal data encryption with pgcrypto
• JWT authentication with role-based access control
• Hash-chained audit trail
• Immutable records for critical data

License

Proprietary - All rights reserved