GuildSpace — Collaboration Platform for Projects & Research

Find collaborators. Build together. Earn trust.

What is GuildSpace?

GuildSpace is a full-stack web platform that solves a problem every student and independent creator faces: you have a project idea, you know what skills you need, and there is no good place to find the right collaborator.

LinkedIn is for jobs. GitHub is for code. Reddit is for chatting. None of them are built for "I'm building this thing — who wants to build it with me?"

GuildSpace bridges that gap with:

An AI-ranked personalised feed that matches project posts to your skill set
A trust score system that rewards contribution and gates access to higher-difficulty projects
A structured application workflow with poster-defined screening questions
In-platform messaging, notifications, and a social follow graph

Built as a DTI capstone project at Bennett University, Greater Noida — April 2026. Team No. 54 · Rishita · Anukriti

Features

For Collaborators

Feature	Description
🤖 AI-ranked feed	Projects ranked by skill overlap, trust compatibility, recency, and difficulty alignment
🔍 Smart search	Find users and projects with debounced inline search and instant dropdown results
📝 Structured apply	Multi-step application form with poster-defined screening questions
📊 Skill match checker	Real-time skill gap analysis shown while filling out an application
🏆 Trust score	Earn trust by completing projects; unlock access to harder collaborations over time
👤 Public profiles	View any user's skills, trust score, and project history
🔔 Notifications	Real-time alerts for new applications, acceptances, follows, and messages
💬 Messaging	In-platform DMs with conversation list and read receipts

For Project Creators

Feature	Description
📌 Project posting	Post with difficulty level (1–10), minimum trust requirement, domain, required skills, and apply type
❓ Custom questions	Define screening questions applicants must answer
🎯 AI applicant ranking	Applicants sorted by AI fit score computed from skill overlap and trust compatibility
✅ Review workflow	Accept, shortlist, or reject applicants directly from the review dashboard
🔒 Post management	Hide, close, or delete posts; three-dot menu with instant actions
📈 Applicant insights	AI-powered per-applicant analysis (via Groq API) with recommendation

Tech Stack

Frontend

React 18          — UI framework
React Router v6   — Client-side routing
CSS Custom Props  — Design system (dark theme, Electric Violet palette)
DM Sans + Syne    — Typography (Google Fonts)
Fetch API         — REST communication

Backend

Python 3.11       — Runtime
FastAPI 0.109     — Web framework + automatic Swagger docs
SQLAlchemy 2.0    — ORM
psycopg2-binary   — PostgreSQL driver
python-jose       — JWT token generation & validation
passlib + bcrypt  — Password hashing
pydantic-settings — Environment variable management
uvicorn           — ASGI server
httpx             — Async HTTP client (Groq API calls)

Database

PostgreSQL 16     — Relational database (13 tables)
pgAdmin           — GUI management

Architecture

┌─────────────────────────────────────────────────────────┐
│                     CLIENT LAYER                        │
│          React 18 · React Router · CSS Vars             │
└─────────────────────┬───────────────────────────────────┘
                      │  HTTPS REST
┌─────────────────────▼───────────────────────────────────┐
│                   API GATEWAY                           │
│          FastAPI · CORS · JWT Auth Middleware           │
└──────┬──────────┬──────────┬───────────┬───────────────┘
       │          │          │           │
  ┌────▼───┐ ┌───▼────┐ ┌───▼────┐ ┌───▼────────────┐
  │ Users  │ │Projects│ │  Apps  │ │ AI / Follow /  │
  │ Auth   │ │  CRUD  │ │ Review │ │ Msgs / Notifs  │
  └────┬───┘ └───┬────┘ └───┬────┘ └───┬────────────┘
       │          │          │           │
┌──────▼──────────▼──────────▼───────────▼──────────────┐
│                    DATA LAYER                          │
│         PostgreSQL 16 · SQLAlchemy ORM                 │
└────────────────────────────────────────────────────────┘

The AI ranking service runs in-process within FastAPI — no external API required for the feed. Groq API is used optionally for per-project and per-applicant insights.

Database Schema

users ──────────── profiles          (1:1)
users ──────────── user_skills       (M:M via skills)
users ──────────── projects          (1:M, creator)
projects ───────── project_skills    (M:M via skills)
projects ───────── project_questions (1:M)
users ──────────── applications      (M:M with projects)
applications ────── application_answers (1:M)
users ──────────── trust_events      (audit log)
users ──────────── follows           (self-referential)
users ──────────── notifications     (1:M)
users ──────────── messages          (self-referential)

13 tables total: users, profiles, skills, user_skills, projects, project_skills, project_questions, applications, application_answers, trust_events, follows, notifications, messages

API Reference

Full interactive docs available at http://localhost:8000/api/docs after starting the server.

Auth & Users

Method	Endpoint	Description
`POST`	`/api/auth/signup`	Create account
`POST`	`/api/auth/login`	Login, returns JWT
`GET`	`/api/users/me`	Get logged-in user's profile
`PUT`	`/api/users/me`	Update profile
`PUT`	`/api/users/me/skills`	Replace skill list

Projects

Method	Endpoint	Description
`GET`	`/api/ai/feed`	AI-ranked personalised feed
`POST`	`/api/projects`	Create a project post
`GET`	`/api/projects`	List all open projects
`GET`	`/api/projects/mine`	My posted projects
`GET`	`/api/projects/{id}`	Single project detail
`PUT`	`/api/projects/{id}`	Update project
`DELETE`	`/api/projects/{id}`	Delete project
`PUT`	`/api/projects/{id}/hide`	Hide from feed

Applications

Method	Endpoint	Description
`POST`	`/api/applications`	Apply to a project
`GET`	`/api/applications/mine`	My submitted applications
`GET`	`/api/applications/project/{id}`	All applicants (creator only)
`PUT`	`/api/applications/{id}/status`	Accept / shortlist / reject

Social & Messaging

Method	Endpoint	Description
`POST`	`/api/users/{id}/follow`	Follow a user
`DELETE`	`/api/users/{id}/follow`	Unfollow
`GET`	`/api/users/{id}/public`	Public profile
`GET`	`/api/search/users`	Search users
`GET`	`/api/search/projects`	Search projects
`POST`	`/api/messages`	Send a message
`GET`	`/api/messages/conversations`	Conversation list
`GET`	`/api/messages/{conversation_id}`	Message thread
`GET`	`/api/notifications`	Notification list
`PUT`	`/api/notifications/read-all`	Mark all as read

Getting Started

Prerequisites

Python 3.11+
Node.js 18+
PostgreSQL 16

1. Clone the repository

git clone https://github.com/your-username/guildspace.git
cd guildspace

2. Set up the database

Open pgAdmin and create a new database named guildspace.

Or via terminal (if psql is in PATH):

psql -U postgres -c "CREATE DATABASE guildspace;"

3. Set up the backend

cd backend

# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # Mac/Linux

# Install dependencies
pip install -r requirements.txt

# Configure environment
copy .env.example .env         # Windows
# cp .env.example .env         # Mac/Linux
# Edit .env with your values (see Environment Variables section)

# Start the server (tables auto-created on first run)
uvicorn main:app --reload --port 8000

4. Set up the frontend

# Open a new terminal
cd frontend

# Install dependencies
npm install

# Configure environment
echo "REACT_APP_API_URL=http://localhost:8000" > .env

# Start the dev server
npm start

5. Open the app

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000
Swagger Docs	http://localhost:8000/api/docs

Environment Variables

Create backend/.env with the following:

# Database
DATABASE_URL=postgresql://postgres:YOUR_PASSWORD@localhost:5432/guildspace

# Auth
SECRET_KEY=your_long_random_secret_key_here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=10080

# App
FRONTEND_URL=http://localhost:3000
DEBUG=True

# Optional — enables AI insights on project detail and applicant review pages
# Get a free key at: https://console.groq.com
GROQ_API_KEY=gsk_your_key_here

Note: The app runs fully without GROQ_API_KEY. The AI feed ranking algorithm works without any external API. Groq is only used for the optional per-project and per-applicant insight text.

Project Structure

guildspace/
├── backend/
│   ├── main.py                    # FastAPI app + router registration
│   ├── requirements.txt
│   ├── .env.example
│   └── app/
│       ├── database/
│       │   ├── config.py          # Pydantic settings
│       │   ├── db.py              # SQLAlchemy engine + session
│       │   └── base.py            # Model imports for table creation
│       ├── models/                # SQLAlchemy ORM models
│       │   ├── user.py
│       │   ├── profile.py
│       │   ├── skill.py
│       │   ├── project.py
│       │   ├── application.py
│       │   ├── trust.py
│       │   ├── follow.py
│       │   ├── notification.py
│       │   └── message.py
│       ├── routes/                # FastAPI routers
│       │   ├── user_routes.py
│       │   ├── project_routes.py
│       │   ├── application_routes.py
│       │   ├── ai_routes.py
│       │   ├── follow_routes.py
│       │   ├── search_routes.py
│       │   ├── notification_routes.py
│       │   └── message_routes.py
│       ├── services/
│       │   ├── ranking_service.py # AI feed ranking algorithm
│       │   └── insight_service.py # Groq API integration
│       ├── middleware/
│       │   └── auth_middleware.py # JWT dependency
│       ├── schemas/               # Pydantic request/response models
│       └── utils/
│           ├── auth.py            # bcrypt + JWT helpers
│           └── helpers.py         # time_ago, trust level, initials
│
└── frontend/
    ├── public/
    └── src/
        ├── api/
        │   └── api.js             # All fetch calls to backend
        ├── context/
        │   └── AuthContext.jsx    # Auth state + JWT management
        ├── components/
        │   ├── Navbar.js          # Top nav with inline search
        │   ├── ApplyModal.jsx     # 3-step application form
        │   ├── ProjectCard.jsx
        │   ├── SkillTag.jsx
        │   └── TrustBadge.jsx
        └── pages/
            ├── Login.jsx          # Login + signup
            ├── Home.js            # AI-ranked feed
            ├── ProjectDetails.js  # Project view + apply
            ├── Profile.jsx        # My profile + collaborations
            ├── Applications.jsx   # Poster review dashboard
            ├── CreateProject.js   # Post a project
            ├── PublicProfile.jsx  # View other users
            ├── Messages.jsx       # In-platform messaging
            ├── Notifications.jsx  # Notification list
            └── SearchPage.jsx     # Search users & projects

AI Ranking Algorithm

The feed ranking algorithm scores each project for a user across 4 components (total 100 pts):

Component	Max Points	Calculation
Skill overlap	40	Matched skills / total required × 40
Trust tier fit	20	Bonus for user trust ≥ project minimum
Recency	20	Posts lose 1pt per 12 hours of age
Difficulty alignment	20	Score based on gap between project difficulty and user's ideal difficulty

Projects are sorted by score (highest first), with already-applied projects pushed to the bottom.

Roadmap

Peer rating after project completion
WebSocket real-time messaging (currently polling)
Email notifications for key events
Cloud deployment (Vercel + Railway + Supabase)
Mobile app (React Native)
Semantic AI matching using sentence embeddings
Project milestone tracking
Organisation / university accounts

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.

GuildSpace — because the best projects are built together.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md
replace_colors.py		replace_colors.py

Folders and files

Latest commit

History

Repository files navigation

GuildSpace — Collaboration Platform for Projects & Research

What is GuildSpace?

Table of Contents

Features

For Collaborators

For Project Creators

Tech Stack

Frontend

Backend

Database

Architecture

Database Schema

API Reference

Auth & Users

Projects

Applications

Social & Messaging

Getting Started

Prerequisites

1. Clone the repository

2. Set up the database

3. Set up the backend

4. Set up the frontend

5. Open the app

Environment Variables

Project Structure

AI Ranking Algorithm

Roadmap

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages