Project Structure

Introduction

This document provides a comprehensive overview of the Citadel Dashboard project structure. Understanding this structure is essential for developers who want to contribute to the project or extend its functionality.

Overall Architecture

The Citadel Dashboard follows a modular monorepo architecture with clearly separated concerns between backend, frontend, and infrastructure components.

citadel-dashboard/
├── backend/                    # Backend server (Node.js, Express, TypeScript)
├── frontend/                   # Frontend application (React, TypeScript, Vite)
├── infra/                      # Infrastructure files
└── package.json                # Root monorepo configuration

Backend Structure

The backend is a Node.js/Express server that provides RESTful APIs for all platform functionality.

backend/
├── config/                     # Configuration files
├── middleware/                 # Express middleware
├── scripts/                    # Utility scripts
├── src/                        # Source code
│   ├── services/               # Business logic services
│   │   ├── adapters/           # Social media platform adapters
│   │   └── *.service.ts        # Service implementations
│   ├── __tests__/              # Test files
│   ├── server.ts               # Main server entry point
│   └── types.ts                # Shared TypeScript types
├── .env                        # Environment variables (not committed)
├── .env.example                # Environment variable template
├── Dockerfile                  # Docker configuration
├── jest.config.js              # Jest test configuration
├── package.json                # Backend package configuration
├── README.md                   # Backend documentation
├── tsconfig.json               # TypeScript configuration
└── [documentation files]       # Project documentation (CHANGELOG.md, etc.)

Backend Services

The backend is organized around service modules that encapsulate business logic:

• auth.service.ts - Authentication and user management
• company.service.ts - Company and organization management
• social-media.service.ts - Social media platform integration
• audit.service.ts - Audit logging and compliance
• rbac.service.ts - Role-based access control
• mfa.service.ts - Multi-factor authentication
• oauth.service.ts - OAuth provider integration
• database.service.ts - Database access layer
• credential-vault.ts - Credential storage in HashiCorp Vault
• client-share.service.ts - Client sharing functionality
• platform-registry.service.ts - Social media platform registry
• enterprise-guard.ts - Enterprise feature protection

Adapters

Platform-specific adapters implement the integration with different social media platforms:

• facebook-adapter.ts - Facebook integration
• twitter-adapter.ts - Twitter/X integration
• instagram-adapter.ts - Instagram integration
• linkedin-adapter.ts - LinkedIn integration

Frontend Structure

The frontend is a modern React dashboard built with TypeScript and Vite, organized by features.

frontend/
├── public/                     # Static assets
├── src/                        # Source code
│   ├── features/               # Feature-based modules
│   │   ├── dashboard/          # Main dashboard components
│   │   ├── content/            # Content management features
│   │   ├── social/             # Social media management features
│   │   ├── analytics/          # Analytics and reporting features
│   │   ├── campaigns/          # Campaign management features
│   │   ├── settings/           # Settings and user management features
│   │   └── index.ts            # Main features export
│   ├── shared/                 # Shared components and utilities
│   │   ├── components/         # Reusable UI components
│   │   └── ...
│   ├── services/               # API services and clients
│   ├── App.tsx                 # Main application component
│   ├── main.tsx                # Application entry point
│   ├── App.css                 # Global styles
│   └── index.css               # Base styles
├── index.html                  # HTML template
├── package.json                # Frontend package configuration
├── README.md                   # Frontend documentation
├── tsconfig.json               # TypeScript configuration
├── tsconfig.app.json           # App-specific TypeScript configuration
├── tsconfig.node.json          # Node-specific TypeScript configuration
├── vite.config.ts              # Vite configuration
└── [config files]              # ESLint and other configuration files

Feature Modules

Each feature module contains all the components, logic, and styles related to a specific functionality area:

Dashboard

• Dashboard.tsx - Main dashboard layout and routing
• Sidebar.tsx - Navigation sidebar
• Header.tsx - Top application header

Content

• AllContent.tsx - Content listing and management
• CreateContent.tsx - Content creation interface
• MediaLibrary.tsx - Media asset management
• Categories.tsx - Content categorization

Social

• Platforms.tsx - Social media platform management
• Calendar.tsx - Content scheduling calendar
• Workflows.tsx - Automation workflows (Enterprise)
• Scheduling.tsx - Content scheduling interface
• Publishing.tsx - Content publishing interface

Analytics

• Analytics.tsx - Analytics dashboard
• Reporting.tsx - Advanced reporting (Enterprise)
• BrandMonitoring.tsx - Brand monitoring (Enterprise)
• CompetitorAnalysis.tsx - Competitor analysis (Enterprise)

Campaigns

• Campaigns.tsx - Campaign management
• CreateCampaign.tsx - Campaign creation interface
• Templates.tsx - Campaign templates

Settings

• Users.tsx - User management
• Settings.tsx - General settings
• AuditLogs.tsx - Audit log viewing
• Integrations.tsx - Third-party integrations
• SSO.tsx - Single Sign-On configuration (Enterprise)

Infrastructure Structure

Infrastructure files for database migrations and deployment configurations.

infra/
├── migrations/                 # Database migration scripts
│   └── 001_create_core_tables.sql
├── db/                         # Database configuration files
└── [config files]              # Deployment and infrastructure configuration

Root Structure

The root directory contains files for monorepo management and project-level configuration.

.
├── package.json                # Root monorepo configuration
├── README.md                   # Project overview and documentation
├── STRUCTURE.md                # This file
├── docker-compose.yml          # Development environment configuration
├── .gitignore                  # Git ignore rules
├── .dockerignore               # Docker ignore rules
├── .env.production.example     # Production environment variables template
├── LICENSE                     # License information
├── SECURITY.md                 # Security policy
├── CONTRIBUTING.md             # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Code of conduct
├── CODEOWNERS                  # Code ownership information
└── [documentation files]       # Project documentation

Development Workflow

Adding New Features

1. For backend features:
   • Create a new service in backend/src/services/
   • Add tests in backend/src/__tests__/
   • Update API routes in backend/src/server.ts
2. For frontend features:
   • Create a new feature module in frontend/src/features/
   • Add components to the appropriate feature directory
   • Export new components in the feature's index.ts
   • Update main dashboard routing in frontend/src/features/dashboard/Dashboard.tsx

Testing

• Backend tests are in backend/src/__tests__/
• Frontend tests would be colocated with components (not currently implemented)

Building and Deployment

• Backend: npm run build in the backend directory
• Frontend: npm run build in the frontend directory
• Both: npm run build from the root directory (uses workspaces)