📋 Table of Contents

• 🚀 Quick Start
• 🏛️ Architecture
• ✨ Features
• 📖 Architecture Decision Records
• ⚡ Tech Stack
• 🛠️ Commands
• 📦 Packages & Services
• 📊 Project Statistics
• 🤝 Contributing
• 📞 Contact

🤖 Agentic Development Setup

IMPORTANT: Developers are strongly encouraged to use these commands to spin up their own local agentic development environment for this project. This is the recommended approach for any sort of agentic development work within the monorepo.

Command	Description
pnpm ai	Starts/detects the server and opens the browser to the latest session
pnpm ai --fresh	Starts a fresh browser session
pnpm ai "your prompt"	Runs prompt asynchronously in the Web UI, continuing the last session
pnpm ai --tui "your prompt"	Runs prompt in the Terminal UI
pnpm ai --native "your prompt"	Runs prompt synchronously in the terminal
pnpm ai --help	Shows all available flags and options

🚀 Quick Start

①	Prerequisites

# Ensure you have Node.js and pnpm installed
node --version    # v18+ recommended
pnpm --version    # v10.12.3

②	Clone & Install

git clone https://github.com/IEEE-Ritb-Website/ieee-ritb-suite.git
cd ieee-ritb-suite
pnpm install

③	Build Everything

pnpm build-all    # Nx-powered build with intelligent caching

④	Configure Environment

cp .env.example .env
# Edit .env with your MongoDB URL and auth credentials

⑤	Start Developing

# Backend service
cd services/backend/<service-name>
pnpm start

# Frontend app (with HMR)
cd services/frontend/<app-name>
pnpm dev

(back to top)

🏛️ Architecture

System Overview

graph TB
    subgraph Packages["📦 Packages"]
        AL["🔊 astralogger<br/><i>Pino Logger</i>"]
        CLI["⚙️ astranova-cli<br/><i>Scaffolding Tool</i>"]
        AI["🤖 astranova-ai<br/><i>AI Assistant</i>"]
        CAT["📚 catalogues<br/><i>Chapter Registry</i>"]
    end

    subgraph Backend["🖥️ Backend Services"]
        ROOT["🌐 root-service<br/><i>Core API</i>"]
        ADMIN["🔐 admin-service<br/><i>Auth & User Admin</i>"]
        COMMON["🛠️ common-app-service<br/><i>Tools & URL Shortener</i>"]
        FORM["📋 form-service<br/><i>Forms & Registration</i>"]
    end

    subgraph Clients["🔌 Client SDKs"]
        RC["@astranova/root-client"]
        AC["@astranova/admin-client"]
        CC["@astranova/common-app-client"]
    end

    subgraph Frontend["🎨 Frontend Apps"]
        LAND["🏠 landing-fe<br/><i>3D Landing Page</i>"]
        LINKS["📋 ieee-links<br/><i>Chapter Showcase</i>"]
        TOOLS["🧰 common-app-fe<br/><i>Dev Tools</i>"]
        PROFILE["👤 profile-fe<br/><i>User Dashboard</i>"]
    end

    subgraph Docs["📖 Documentation"]
        ADR["📝 docs/adrs/<br/><i>Architecture Decisions</i>"]
    end

    Packages --> Backend
    Packages --> Frontend

    ROOT --> RC
    ADMIN --> AC
    COMMON --> CC

    RC --> LAND
    CC --> TOOLS

Loading

Directory Structure

ieee-ritb-suite/
│
├── 📦 packages/                      # Shared libraries
│   ├── 🔊 astralogger/              # Pino-based logging utility
│   ├── ⚙️ astranova-cli/            # Custom scaffolding CLI
│   ├── 🤖 astranova-ai/             # Just runs OpenCode
│   ├── 📦 astranova-core/           # Core environment and monorepo root helpers
│   └── 📚 catalogues/               # IEEE chapter data registry (18 chapters)
│
├── 🔌 shared-clients/           # Centralized API client singletons (with client-config.json)
│
├── 🔧 services/
│   │
│   ├── 🖥️ backend/                  # Express.js microservices
│   │   ├── 🔐 admin-service/        # Auth & user administration
│   │   ├── 🌐 root-service/         # Core public API
│   │   ├── 🛠️ common-app-service/   # Dev tools backend & URL shortener
│   │   └── 📋 form-service/         # Forms & event registration
│   │
│   └── 🎨 frontend/                 # Vite + React frontends
│       ├── 🏠 landing-fe/           # 3D landing page
│       ├── 🧰 common-app-fe/        # Developer tools dashboard
│       ├── 📋 ieee-links/           # Chapter link showcase
│       └── 👤 profile-fe/           # Next.js user dashboard
│
├── 📖 docs/
│   └── 📝 adrs/                     # Architecture Decision Records
│
└── 📜 scripting/                    # CLI entry point

(back to top)

✨ Features

🛠️ Custom CLI	Scaffold new services instantly with pnpm rs create-be/fe - generates TypeScript, ESLint, Zod, and all configs automatically
🔗 Workspace Linking	Shared packages auto-link via workspace:* protocol - no manual linking or publishing required
⚡ Nx Build Caching	Intelligent builds that only rebuild what changed - dramatically faster CI/CD pipelines
🔊 Unified Logging	Shared Pino-based logger across all services via astralogger package with environment-aware levels
📚 Chapter Registry	Single source of truth for 18 IEEE chapters with Zod-validated schemas
🌐 3D Landing Page	Stunning Three.js + React Three Fiber powered landing with WebGL effects

(back to top)

📖 Architecture Decision Records

Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions made during the project's development. Each ADR records a specific decision, its context, the options considered, and the rationale for the chosen approach.

Purpose: ADRs provide a historical record of why the project is built the way it is — helping current and future contributors understand the reasoning behind key choices without needing to rediscover or debate them again.

Location: docs/adrs/

ADR	Title	Decision
ADR-001	pnpm as Package Manager	Why pnpm was chosen over npm and Yarn
ADR-002	Nx Build System	Why Nx was chosen for monorepo orchestration
ADR-003	Monorepo Architecture	Why a monorepo structure was adopted
ADR-004	React Hook Form with Zod	Why react-hook-form and Zod are used for form validation
ADR-005	Cron Jobs for Backend Services	Why cron jobs are used (Render free tier constraints)
ADR-006	CI/CD and Deployment Strategy	Deployment targets and pipeline choices
ADR-007	Client SDK Pattern	Typed API client packages co-located with backend services
ADR-008	Centralized Clients & Core Split	Instantiated client singletons in shared-clients and astranova-core entrypoints

(back to top)

⚡ Tech Stack

Category	Technologies
🏗️ Build System
🖥️ Backend
🎨 Frontend
🎬 3D/Animation

(back to top)

🛠️ Commands

📥 Setup & Installation

Command	Description
pnpm install	Install all workspace dependencies
pnpm build-all	Build all packages and services with Nx caching

🆕 Scaffolding New Services

Command	Description
pnpm rs create-be <name>	Create new Express backend in services/backend/
pnpm rs create-fe <name>	Create new Vite+React frontend in services/frontend/

🤖 AI Command Assistant (astranova-ai)

The suite includes a project-local AI developer assistant wrapper (astranova-ai, aliased as ai) that calls OpenCode. It runs prompts in the Web UI (--web, default), Terminal UI (--tui), or headlessly in the terminal (--native).

Command	Description
pnpm ai	Starts/detects the server and opens the browser to the latest session
pnpm ai --fresh	Starts a fresh browser session
pnpm ai "your prompt"	Runs prompt asynchronously in the Web UI, continuing the last session
pnpm ai --fresh "your prompt"	Runs prompt asynchronously in the Web UI in a fresh session
pnpm ai --tui "your prompt"	Runs prompt in the Terminal UI, continuing the last session
pnpm ai --tui --fresh "your prompt"	Runs prompt in the Terminal UI in a fresh session
pnpm ai --native "your prompt"	Runs prompt synchronously directly in the terminal, continuing the last session
pnpm ai --native --fresh "your prompt"	Runs prompt synchronously in the terminal as a fresh session

🖥️ Backend Development

cd services/backend/<service-name>

Command	Description
pnpm start	Run compiled code (node dist/index.js)
pnpm run build	TypeScript compile (tsc && tsc-alias)
pnpm run lint	Run ESLint

🎨 Frontend Development

cd services/frontend/<app-name>

Command	Description
pnpm dev	Vite dev server with HMR
pnpm run build	TypeScript + Vite production build
pnpm run preview	Preview production build
pnpm run lint	Run ESLint

📊 Nx Operations

Command	Description
nx run-many --target=build --all	Build all projects with caching
nx graph	Visualize dependency graph

(back to top)

📦 Packages & Services

Shared Packages

Package	Description	Key Features
🔊 astralogger	Pino-based logging utility	Singleton pattern, env-aware levels, astralogger.json config
⚙️ astranova-cli	Custom scaffolding tool	Generates Express/Vite apps with TypeScript, ESLint, Zod
🤖 astranova-ai	Local AI developer assistant CLI wrapper	Terminal or Web UI execution modes, dynamic project-local binary resolution
📦 astranova-core	Core environment and path helpers	Separate browser-safe and Node-only entrypoints, CommonJS compatible
📚 @astranova/catalogues	IEEE chapter data registry	Zod-validated schemas, 18 chapters (12 tech, 6 non-tech)
🔌 shared-clients	Centralized instantiated clients	Singleton API client exports, client-config.json urls, local health checks

Frontend Applications

App	Description	Key Technologies
🏠 landing-fe	3D landing page	Three.js, React Three Fiber, Lenis
🧰 common-app-fe	Developer tools dashboard	Radix UI, React Router, UUID/JSON/Hash generators
📋 ieee-links	Chapter link showcase	Framer Motion
👤 profile-fe	User dashboard & auth	Next.js 16, better-auth

Backend Services

Service	Description	Key Features
🔐 admin-service	Auth & user admin	better-auth, Cloudinary, exports auth-client
🌐 root-service	Core public API	Express v5, MongoDB, chapter catalogues
🛠️ common-app-service	Dev tools backend & URL shortener	REST APIs, ritb.in short URLs, cron endpoint
📋 form-service	Forms & event registration	Zod validation, MongoDB

(back to top)

📊 Project Statistics

Metric	Count
📦 Shared Packages	5
🖥️ Backend Services	4
🎨 Frontend Apps	4
📖 ADR Documents	8

🤝 Contributing

We welcome contributions! Here's how to get started:

🔧 Setup

① Fork this repository
② Clone your fork: git clone <your-fork-url>
③ Create branch: git checkout -b feature-name
④ Install: pnpm install (from root)
⑤ Build: pnpm build-all

💻 Development Guidelines

Guideline	Description
Custom CLI	Use pnpm rs create-be/fe <name> to scaffold new services
Patterns	Follow existing patterns in services/backend/ or services/frontend/
Architecture	Review docs/adrs/ before making architectural decisions
Shared Packages	Utilize astralogger and catalogues
Path Aliases	Use @/ prefix for imports: import { x } from "@/utils/x"
TypeScript	Maintain strict mode compliance

📤 Submitting

① Test your changes thoroughly
② Lint: pnpm run lint (in service directory)
③ Build: Verify pnpm run build succeeds
④ Commit: Follow conventional commits
⑤ Push: git push origin feature-name
⑥ PR: Create pull request against main branch
⑦ Checks: Ensure all CI checks pass

(back to top)

📞 Contact

Maintained by Shivesh & Ahad

For issues and feature requests, please open an issue

Built with ❤️ by IEEE RIT Bangalore