📂 Shadow Syndicate – Cyberpunk Hacker Syndicate Management Game

Created by: Mridul Jha Year: 2088 Location: Neo‑Veridia

1️⃣ Project Overview

What is Shadow Syndicate?

Shadow Syndicate is a web‑based management simulation where you run a covert cyber‑hacker syndicate in the neon‑lit megacity of Neo‑Veridia. You recruit operatives, plan infiltrations against powerful megacorporations, purchase cutting‑edge cyberware on the Black Market, and climb a global leaderboard based on your accumulated Net Worth.

Core Premise & Setting

In 2088, megacorp data vaults are the new gold mines. A rag‑tag crew of hackers (your Agents) can breach these vaults, steal credits, and sell stolen data. The world is drenched in dark cyber‑punk aesthetics—rain‑slick streets, towering holo‑ads, and neon glows of #00F0FF cyan, #00FF66 emerald, and #FF0055 scarlet. Every decision you make pushes you deeper into the shadowy underworld of Veridia.

Target Audience

Fans of cyber‑punk fiction & aesthetics
Players who enjoy incremental/idle management sims
Developers who love a clean Node‑Express codebase with real‑time features

Tech Stack Overview

Layer	Technology	Purpose
Backend	Node.js, Express.js, `express‑session`, `bcryptjs`	API, authentication, raid resolution worker
Database	PostgreSQL (hosted on Neon.tech)	Persistent storage for users, agents, raids, market, inventory
Frontend	EJS templating, Tailwind‑CSS (custom neon palette)	Server‑side rendered UI with responsive design
Real‑time	`node‑cron` worker (10 s tick) + client‑side JS countdown	Automatic raid resolution and live timers
Deployment	Render (Web Service) + Neon.tech (PostgreSQL)	Production‑grade hosting

2️⃣ Getting Started / Installation

⚡ Quick one‑liner

git clone https://github.com/your‑org/shadow‑syndicate && cd shadow‑syndicate && cp .env.example .env && npm i && npm run dev

Prerequisites

Tool	Minimum version
Node.js	18.x
npm	9.x (bundled with Node)
Git	any recent release
PostgreSQL client	`psql` (optional, for manual inspection)

Clone & Setup

# 1️⃣ Clone the repo
git clone https://github.com/your-org/shadow-syndicate.git
cd shadow-syndicate

# 2️⃣ Install dependencies
npm install

Environment Variables

Create a .env file at the project root (you can copy from .env.example).

Variable	Description
`DATABASE_URL`	PostgreSQL connection string from Neon.tech
`SESSION_SECRET`	Random string for signed cookies (e.g., `openssl rand -hex 32`)
`PORT`	Port for the Express server (default `3000`)
`NODE_ENV`	`development` or `production`

Example .env

DATABASE_URL=postgres://user:password@db.neon.tech/shadow_syndicate
SESSION_SECRET=5f2e3d1c9ab7e6d1c8f0f4a9b2c3d4e5
PORT=3000
NODE_ENV=development

Database Setup

Create the schema – run the supplied schema.sql. It creates tables for users, agents, raids (templates), raid_logs (instances), market_items, user_inventory, and transactions.
```
psql $DATABASE_URL -f schema.sql
```
Seed the market – the seed_market.sql script pre‑populates the Black Market with the three starter items.
```
psql $DATABASE_URL -f seed_market.sql
```

💡 Tip: Neon.tech provides a free tier suitable for development; you can copy the connection string from the Neon dashboard.

Running Locally

# Development mode (auto‑restart with nodemon)
npm run dev   # runs `nodemon server.js`

# Production mode
node server.js

The app will be reachable at http://localhost:3000 (or the port you set).

First‑Login Flow

Register a new account on the /register page – you start with 1,000 CR.
Login on /login. The Dashboard shows your Liquid Credits and a prompt to recruit your first operative.
From there, you can recruit agents, launch raids, and visit the Black Market.

3️⃣ Game Mechanics – Complete Rules

A. 💰 Credits System

Item	Details
Starting balance	1,000 CR (awarded on registration)
Income sources	• Raid rewards (see Raids) • Sale of market items (future feature)
Expenses	• Recruiting an Agent (500 CR each) • Purchasing Black‑Market items (price per item)
Display	Shown as LIQUID CREDITS on the top‑right of the Dashboard and on the Leaderboard
Why it matters	Credits unlock new agents, power‑up equipment, and ultimately increase your Net Worth for leaderboard ranking.

B. 🕵️‍♂️ Agent Recruitment & Classes

Class	Hacking Power	Role
Netrunner	15‑25	Fast, stealthy infiltrations; best for EASY raids
Enforcer	20‑30	Brute‑force access; higher chance of success on MEDIUM raids
Decryptor	10‑20	Specialized in cipher‑breaking; higher reward on data‑heavy raids

Recruitment cost: 500 CR per operative.
Agent status: IDLE – ready for a raid; ON_RAID – deployed; RECOVERED – cooldown after a raid (future expansion).
Recruitment UI: Dashboard → RECRUIT OPERATIVE → select class → confirm.
Stats stored per agent: name, class, hacking_power, level (default 1), health/max_health, energy/max_energy, status.
No hard cap on the number of agents; each costs 500 CR, so credit management is essential.

C. ⚔️ Raids System

Target Corp	Difficulty	Duration (s)	Reward (CR)
Aegis Corp	EASY	30	300
OmniData	MEDIUM	45	600
Quantum Dynamics	HARD	60	1,200

How to launch a raid

Navigate to /raids.
Pick a corporate target card.
Select an IDLE agent from the dropdown.
Click LAUNCH INFILTRATION.

Raid lifecycle

State	Meaning
`IN_PROGRESS`	The raid timer is counting down (client‑side countdown).
`SUCCESS`	Server resolves after the duration; credits added to your account.
`FAILED`	No credits awarded; the agent returns `IDLE`.

Success rate: Fixed 85 % (the server rolls a random number on resolution).
Resolution: A node‑cron worker runs every 10 seconds, checks for raids whose end‑time has passed, updates status, credits, and agent state.
History: All completed raids appear in MISSION HISTORY LOGS with columns for Log ID, Target, Agent, Outcome, Credit Payout, and Completion Time.
Live countdown: Client‑side JavaScript updates every second, displaying MM:SS.

D. 🛒 Black Market System

Item	Price (CR)	Type	Bonus
Quantum Decryptor Node	1,200	Cyberware	+8 Hack stat (equip to an agent)
Aegis Shield Bypass Key	2,500	Utility/Gadget	+6 Stealth stat (reduces detection)
Encrypted Corporate Data Chip	800	Consumable/Data	No direct stat boost; can be resold for profit

Buying flow

Go to /market.
Choose an item, set a quantity, click PURCHASE.
The server validates: enough Liquid Credits and enough stock. If successful, credits are deducted, stock reduced, and the item added to your Syndicate Inventory.

Inventory tracking

The ACQUIRED SYNDICATE INVENTORY section lists each owned item, quantity, and total asset value (quantity × price_per_unit).
Items can later be equipped to specific agents (future expansion).

Stock limits

Each market item has a finite stock (default 10). Stock refreshes only via admin tools or future events.

E. 🌟 Rating, Rank & Reputation System

Metric	How it changes
Reputation	+1 per successful raid (no penalty for failure)
Syndicate Rank	Determined by reputation thresholds (see table)
Leaderboard	Global ranking by Net Worth (Credits + Inventory value)

Rank progression

Reputation	Rank Title
0‑0	Novice Operator (default)
1‑5	Rising Shadow
6‑15	Net Master
16‑30	Syndicate Legend
31+	Neo‑Veridia Phantom (max)

Badge display: Top‑3 displayed as 🥇 🥈 🥉. Others show #N.
Why it matters: Higher rank grants access to rare market items, special hard‑mode raids, and pure bragging rights.

F. 📈 Net Worth Calculation

Net Worth = Liquid Credits + Σ (quantity_i × price_per_unit_i)   for all owned items

Liquid Credits = user.credits column.
Inventory Asset Value = sum of each inventory line's market price multiplied by owned quantity.
Shown on the Leaderboard under the TOTAL NET WORTH column, and used as the sorting key for global ranking.

4️⃣ Game Loop & How to Win

Objective: Maximize Net Worth and climb to the top of the global leaderboard.

Core Loop

Recruit agents (costs credits, expands your raid roster).
Launch raids with idle agents → earn credits & reputation.
Visit the Black Market → spend credits on stat‑boosting gear and collectible items.
Repeat – each successful raid fuels more purchases, which in turn raise the value of your inventory (Net Worth).

Winning Conditions

Goal	Description
#1 Global Rank	Be the top player on the Leaderboard (Net Worth highest).
Max Reputation	Reach the Neo‑Veridia Phantom title (31+ successful raids).
Infinite Net Worth	There is no hard cap; the game is designed for endless growth.
Personal Milestones	Unlock every market item, own a full roster of agents, complete all raids.

⏳ No time limit – raids run in the background, allowing you to step away and return when they finish.

5️⃣ Features & Pages Explained

📊 Dashboard

Stat Overview – Liquid Credits, Reputation rank badge, active agents count.
Recruitment Panel – Form to hire a new operative (class selector, 500 CR cost).
Agent Roster – Grid of agent cards: name, class, hacking power, status badge, health bar.
Empty State – If you have no agents, a call‑to‑action encourages you to recruit.

⚡ Raids

Target Facility Cards – Show difficulty, duration, reward; disabled if you lack idle agents.
Active Operations – Live list of in‑progress raids with real‑time countdown timers.
Mission History – Table summarizing every raid (success/failure, credits earned, timestamps).

🛍️ Black Market

Item Catalog – Card view of each market item with price, type, and bonus description.
Purchase Form – Quantity selector, PURCHASE button; instant credit deduction.
Inventory Section – Displays owned items, total quantity, and combined asset value.
Stock Indicator – Red badge if an item is out of stock.

🏆 Leaderboard

Global Ranking – Sorted descending by Net Worth.
Columns: Rank, Operative (username), Reputation, Liquid Credits, Inventory Value, Total Net Worth.
Current user row highlighted with a “YOU” badge and distinct background.
Medals for top three; subsequent rows numbered.
Auto‑refreshes when you earn credits or purchase items.

6️⃣ Strategy & Tips

Phase	Suggested Playstyle
Early Game	Recruit 2‑3 agents (mix Netrunner & Enforcer). Focus on EASY raids (Aegis Corp) for steady cash flow. Keep a small credit reserve (≈300 CR).
Mid Game	Purchase Quantum Decryptor Nodes to boost hacking power; start tackling MEDIUM raids (OmniData). Monitor agent health – a failed raid can trigger a health penalty (future update).
Late Game	Optimize teams: pair high‑hacking Netrunners with Decryptors for data‑heavy raids. Invest in Aegis Shield Bypass Keys to lower detection on HARD raids. Keep an eye on the Leaderboard, and aim for the top‑3 medals.
General Tips	- Diversify: Different classes excel in different raid types. - Reserve Credits: Always keep at least 500 CR for a surprise recruitment. - Market Timing: Buy items early (when you have surplus credits) to increase Net Worth quickly. - Agent Rotation: Cycle agents to avoid long idle periods; the more raids you run, the faster you climb.

7️⃣ Terminology Glossary

Term	Definition
Agent	Operative you recruit (Netrunner, Enforcer, Decryptor).
Raid	Timed infiltration mission against a corporate target.
Credits (CR)	In‑game currency used for recruitment & market purchases.
Hacking Power	Numeric stat determining raid success chance.
Net Worth	Sum of Liquid Credits + Inventory Asset Value.
Reputation	Points earned per successful raid; drives Rank titles.
Leaderboard	Global ranking based on Net Worth.
Status	`IDLE`, `ON_RAID`, `RECOVERED` – agent availability.
Inventory	Collection of purchased market items.
Cooldown	(Future) period after a raid before an agent can be reused.

8️⃣ Technical Details (For Developers)

Database Schema (high‑level)

users(id, username, email, password_hash, credits, reputation)
agents(id, user_id, name, class, hacking_power, level, health, max_health, energy, max_energy, status)
raids(id, corp_name, difficulty, duration_seconds, reward_credits) – static templates.
raid_logs(id, user_id, agent_id, corp_name, start_time, end_time, status, credit_earned) – each launched raid.
market_items(id, name, type, price, stock, bonus_json) – defines items.
user_inventory(id, user_id, item_id, quantity) – many‑to‑many relation.
transactions(id, user_id, amount, type, description, created_at) – audit trail.

Raid Resolution Worker

// src/cron/resolveRaids.js
cron.schedule('*/10 * * * * *', async () => {
  const expired = await db.query(`SELECT * FROM raid_logs WHERE end_time <= NOW() AND status = 'IN_PROGRESS'`);
  for (const raid of expired.rows) {
    await db.transaction(async (trx) => {
      const success = Math.random() < 0.85;
      const credit = success ? raid.reward_credits : 0;
      // Update raid log
      await trx.query(`UPDATE raid_logs SET status = $1, credit_earned = $2 WHERE id = $3`, [
        success ? 'SUCCESS' : 'FAILED',
        credit,
        raid.id,
      ]);
      // Return agent to IDLE
      await trx.query(`UPDATE agents SET status = 'IDLE' WHERE id = $1`, [raid.agent_id]);
      // Credit user (if success)
      if (success) {
        await trx.query(`UPDATE users SET credits = credits + $1, reputation = reputation + 1 WHERE id = $2`, [
          credit,
          raid.user_id,
        ]);
      }
    });
  }
});

Runs every 10 seconds (cron expression */10 * * * * *). Uses ACID transactions (BEGIN/COMMIT/ROLLBACK) to guarantee credit consistency.

Session Management

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: { maxAge: 24 * 60 * 60 * 1000 } // 24 h
}));

Sessions stored in memory for dev, can switch to connect‑pg for production.

Authentication

Passwords hashed with bcryptjs (12 salt rounds). Unique constraints on username and email enforced at DB level (UNIQUE).

Real‑time UI

No WebSocket needed; the client polls the countdown timer via client‑side JavaScript (setInterval).
Leaderboard refreshes on page load; an optional AJAX endpoint (/api/leaderboard) can be added later.

9️⃣ Deployment

Platform	Steps
Render (Web Service)	1. Create a new Web Service. 2. Connect the Neon.tech PostgreSQL add‑on. 3. Add environment variables (`DATABASE_URL`, `SESSION_SECRET`, `PORT`, `NODE_ENV=production`). 4. Set Build Command = `npm install`. 5. Set Start Command = `node server.js`.
Neon.tech (PostgreSQL)	1. Create a new project and database. 2. Copy the connection string into Render’s env vars. 3. Run `psql $DATABASE_URL -f schema.sql` and `psql $DATABASE_URL -f seed_market.sql` via Neon’s console or your local `psql`.
Static Assets	Tailwind CSS is compiled at build time via a simple `postcss` script (`npm run build-css`). Ensure the compiled file is served from `/public/css`.

Production env vars (example):

DATABASE_URL=postgres://user:pw@db.neon.tech/shadow_syndicate
SESSION_SECRET=YOUR_RANDOM_64_BYTE_STRING
PORT=10000
NODE_ENV=production

🔟 Credits & Attribution

Role	Person / Entity
Game Design & Lead Development	Mridul Jha – GitHub: @Loki‑Snape
Concept Art & UI Themes	(In‑house, cyber‑punk reference packs)
Backend Architecture	Mridul Jha (Node / Express)
Frontend Styling	Tailwind CSS (custom neon palette)
Database	PostgreSQL, hosted on Neon.tech
Real‑time Logic	`node‑cron` worker
Inspiration	Classic cyber‑punk literature, Blade Runner, Neuromancer, and management sims such as Software Inc. and Stellaris
Third‑party Libraries	`express`, `express‑session`, `bcryptjs`, `ejs`, `pg`, `node‑cron`, `dotenv`, `tailwindcss`

If you contributed code, artwork, or ideas, feel free to add your name here!

🎮 Happy Hacking!

Dive into Neo‑Veridia, assemble a crew of unstoppable operatives, and prove that you’re the true Shadow Syndicate. May your Net Worth sky‑rocket, your reputation blaze across the Leaderboard, and the neon lights of the city never dim on your exploits.

For bugs, feature requests, or to share your highest score, open an issue on the GitHub repository.

Name		Name	Last commit message	Last commit date
config		config
controllers		controllers
middleware		middleware
routes		routes
views		views
workers		workers
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
schema.sql		schema.sql
server.js		server.js

Latest commit

History

Folders and files

Repository files navigation