ProofStack 2.0

🌐 Live Application

ProofStack 2.0 is deployed as a full-stack production application.

Live Frontend: https://proof-stack-blond.vercel.app
Backend API: https://proofstack-api.onrender.com
Interactive API Documentation: https://proofstack-api.onrender.com/docs
API Health Check: https://proofstack-api.onrender.com/api/health

Note: The backend is hosted on Render's free tier. After a period of inactivity, the service may spin down, so the first request can take approximately 50 seconds or more while the server starts.

🚀 Production Architecture

                     PROOFSTACK 2.0

                          User
                            │
                            ▼
                ┌─────────────────────┐
                │    React + Vite     │
                │      Frontend       │
                │       Vercel        │
                └──────────┬──────────┘
                           │
                      REST API / HTTPS
                           │
                           ▼
                ┌─────────────────────┐
                │      FastAPI        │
                │       Backend       │
                │       Render        │
                └──────────┬──────────┘
                           │
                           ▼
                ┌─────────────────────┐
                │     SQLAlchemy      │
                │        ORM          │
                └──────────┬──────────┘
                           │
                           ▼
                ┌─────────────────────┐
                │     PostgreSQL      │
                │      Supabase       │
                └─────────────────────┘

Production Stack

Layer	Technology	Hosting
Frontend	React + Vite	Vercel
Backend	Python + FastAPI	Render
API	REST	Render
ORM	SQLAlchemy	Backend
Database	PostgreSQL	Supabase
Authentication	JWT	FastAPI
Local Database	SQLite	Local Development

The production frontend communicates with the FastAPI backend through HTTPS REST API requests. The backend handles authentication and application logic and persists production data in PostgreSQL through SQLAlchemy.

🗄️ Database Environments

ProofStack uses separate database configurations for local development and production.

Local Development: SQLite
Production: PostgreSQL hosted on Supabase
Database ORM: SQLAlchemy

This keeps local development lightweight while allowing the deployed application to use PostgreSQL as its production database.

✅ Production Deployment Status

Planned Improvements

Dockerized runtime
GitHub automatic evidence ingestion
Semantic retrieval
LLM integration

Evidence-Based Technical Skill Intelligence Platform

ProofStack is a full-stack application that turns technical skills into evidence-backed capabilities.

Instead of simply listing skills such as Python, FastAPI, or React, users attach those skills to projects and technical evidence. ProofStack then analyzes that evidence to build a skill-intelligence profile, compare demonstrated skills against job requirements, identify evidence gaps, and answer questions grounded in the user's own technical history.

Don't just claim what you know. Show the evidence.

Why ProofStack?

Traditional resumes and portfolios often represent technical ability as a simple list:

Python
FastAPI
React
SQL
Docker

That tells an employer what someone claims to know, but not what they have actually built with those technologies.

ProofStack uses a different model:

Technical Work
      ↓
Evidence
      ↓
Skills
      ↓
Skill Intelligence
      ↓
Job Requirement Comparison
      ↓
Grounded Career Insights

The central idea is simple:

A skill becomes more meaningful when it is connected to evidence.

Application Preview

Evidence-Based Technical Profile

Users create technical evidence and associate it with projects and skills.

Evidence can represent:

Projects
Work experience
Certifications
Courses
Technical practice

Each evidence item can demonstrate multiple technical skills.

Projects and Skill Relationships

ProofStack connects projects, evidence, and technical skills instead of storing them as unrelated text fields.

Conceptually:

User
  ↓
Project
  ↓
Evidence
  ↓
Skills

This allows ProofStack to answer questions such as:

Which projects demonstrate FastAPI?
What evidence supports Python?
How many pieces of evidence support a particular skill?
Which skills are supported across multiple projects?

Skill Intelligence

ProofStack converts stored evidence into an evidence-backed skill profile.

The intelligence dashboard considers signals such as:

Supporting evidence
Number of projects
Evidence diversity
Evidence type

Example:

React        44/100
FastAPI      44/100
JWT          44/100
Python       44/100

These values represent evidence confidence, not technical mastery.

A score of 44/100 does not mean that a user knows only 44% of a technology.

It means ProofStack currently has limited stored evidence supporting that skill.

Job Evidence Analysis

Users can paste a technical job description into ProofStack.

The application extracts supported technical requirements and compares them against the user's stored evidence.

For example, a job may require:

Python
FastAPI
React
JWT
PostgreSQL
Docker
REST API
Git

If ProofStack contains evidence for:

Python
FastAPI
React
JWT

the application identifies:

MATCHED

Python
FastAPI
React
JWT

and:

MISSING EVIDENCE

PostgreSQL
Docker
REST API
Git

The resulting:

Evidence Coverage: 50%

means that stored ProofStack evidence supports 50% of the identified technical requirements.

It is not a hiring probability or candidate ranking score.

Grounded Evidence Assistant

ProofStack also includes an assistant that answers questions using the user's stored technical evidence.

Example question:

What evidence do I have for FastAPI?

Instead of returning a generic explanation of FastAPI, ProofStack searches the user's stored evidence and returns relevant technical work.

The assistant is intentionally designed around:

Question
   ↓
Stored User Evidence
   ↓
Relevant Evidence Retrieval
   ↓
Grounded Response

This prevents the application from presenting technical experience that the user has not actually stored.

Core Features

Authentication

User registration
Secure password hashing
Login
JWT authentication
Protected API endpoints
User-specific data isolation
Session expiration handling

Evidence Management

Create evidence
Retrieve evidence
Update evidence
Delete evidence
Associate evidence with projects
Attach multiple skills to evidence

Projects

Create technical projects
Organize evidence by project
Connect projects with demonstrated skills

Skill Intelligence

Evidence-backed skill scoring
Evidence counts
Project counts
Evidence-strength classification
Skill intelligence dashboard

Job Analyzer

Technical requirement extraction
Skill alias normalization
Overlapping phrase detection
Matched skill identification
Missing evidence identification
Evidence coverage calculation

Grounded Assistant

Questions about stored technical evidence
Evidence retrieval
Skill-aware matching
Grounded responses
No invented experience

Validation and Error Handling

Frontend input validation
Backend Pydantic validation
API error handling
Authentication failure handling
Session expiration handling

Automated Testing

API health tests
Authentication tests
Job analyzer tests
Alias normalization tests
Evidence workflow integration tests

Technology Stack

Frontend

Technology	Purpose
React	User interface
JavaScript	Frontend application logic
Vite	Development/build tooling
HTML	Application structure
CSS	Application styling

Backend

Technology	Purpose
Python	Backend programming language
FastAPI	REST API framework
Pydantic	Request and response validation
SQLAlchemy	Object-relational mapping
JWT	Authentication
Password Hashing	Secure password storage

Database

Technology	Purpose
SQLite	Current local development database
SQLAlchemy ORM	Database abstraction and relational modeling

Testing

Technology	Purpose
Pytest	Automated backend testing
FastAPI TestClient	API integration testing

System Architecture

                         USER
                          │
                          ▼
                  ┌───────────────┐
                  │ React + Vite  │
                  │   Frontend    │
                  │ localhost:5173│
                  └───────┬───────┘
                          │
                          │ REST / JSON
                          │ JWT
                          ▼
                  ┌───────────────┐
                  │    FastAPI    │
                  │    Backend    │
                  │ localhost:8000│
                  └───────┬───────┘
                          │
             ┌────────────┼────────────┐
             │            │            │
             ▼            ▼            ▼
       Authentication  Services    Validation
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
           Skill          Job       Grounded
        Intelligence    Analyzer    Assistant
             │            │            │
             └────────────┼────────────┘
                          │
                          ▼
                  ┌───────────────┐
                  │  SQLAlchemy   │
                  │      ORM      │
                  └───────┬───────┘
                          │
                          ▼
                  ┌───────────────┐
                  │    SQLite     │
                  │   Database    │
                  └───────────────┘

For a more detailed explanation, see:

ARCHITECTURE.md

Relational Data Model

ProofStack is built around relationships between users, projects, evidence, and skills.

USER
 │
 ├────────────── PROJECT
 │                  │
 │                  ▼
 │               EVIDENCE
 │                  │
 │                  ▼
 └─────────────── SKILLS

The important relationship is:

Evidence ←→ Skills

An evidence item can demonstrate multiple skills:

Built authenticated React and FastAPI application
                 │
       ┌─────────┼─────────┬─────────┐
       ▼         ▼         ▼         ▼
     React    FastAPI     JWT      Python

A skill can also be supported by multiple evidence items.

This creates a many-to-many relationship implemented through an evidence-skill association table.

Authentication Flow

ProofStack uses JWT authentication.

User
  ↓
Email + Password
  ↓
POST /api/auth/login
  ↓
FastAPI
  ↓
Verify Password
  ↓
Generate JWT
  ↓
React Stores Token
  ↓
Authenticated API Requests

Protected requests include:

Authorization: Bearer <JWT>

The backend validates the token before allowing access to user-specific resources.

Job Analyzer

The Job Analyzer follows an explainable rule-based pipeline.

Job Description
      ↓
Normalize Text
      ↓
Identify Technical Phrases
      ↓
Normalize Skill Aliases
      ↓
Canonical Skills
      ↓
Compare Against Evidence
      ↓
Matched / Missing
      ↓
Evidence Coverage

Skill Alias Normalization

Different job descriptions may refer to the same technology using different names.

ProofStack normalizes these aliases.

Examples:

React.js
ReactJS
React
    ↓
React

Postgres
PostgreSQL
    ↓
PostgreSQL

JWT Authentication
JSON Web Token
JWT
    ↓
JWT

REST API
REST APIs
RESTful API
    ↓
REST API

K8s
    ↓
Kubernetes

Amazon Web Services
    ↓
AWS

Overlapping Phrase Detection

Skill extraction also handles overlapping aliases.

For example:

React.js

contains the characters:

js

A naive keyword system could incorrectly identify both:

React
JavaScript

ProofStack prioritizes the longer meaningful technical phrase so:

React.js
   ↓
React

without incorrectly generating JavaScript evidence.

This behavior is covered by automated tests.

API Structure

ProofStack separates API endpoints by responsibility.

backend/app/routers/
│
├── auth.py
├── projects.py
├── evidence.py
├── intelligence.py
├── jobs.py
└── assistant.py

The business logic is separated into services:

backend/app/services/
│
├── scoring.py
├── job_analysis.py
└── assistant.py

This keeps HTTP routing separate from application logic.

Backend Project Structure

backend/
│
├── app/
│   ├── routers/
│   │   ├── auth.py
│   │   ├── projects.py
│   │   ├── evidence.py
│   │   ├── intelligence.py
│   │   ├── jobs.py
│   │   └── assistant.py
│   │
│   ├── services/
│   │   ├── scoring.py
│   │   ├── job_analysis.py
│   │   └── assistant.py
│   │
│   ├── config.py
│   ├── database.py
│   ├── dependencies.py
│   ├── main.py
│   ├── models.py
│   ├── schemas.py
│   └── security.py
│
├── tests/
│   ├── test_auth.py
│   ├── test_evidence_flow.py
│   ├── test_health.py
│   └── test_job_analysis.py
│
├── .env.example
└── requirements.txt

Frontend Project Structure

frontend/
│
├── src/
│   ├── App.jsx
│   ├── App.css
│   ├── index.css
│   └── main.jsx
│
├── index.html
├── package.json
├── package-lock.json
└── vite.config.js

Running ProofStack Locally

Prerequisites

Install:

Python 3
Node.js
npm
Git

Docker is not required to run the current local version.

1. Clone the Repository

git clone https://github.com/ThejeswarReddy661/ProofStack.git

Enter the project:

cd ProofStack

Backend Setup

Enter the backend:

cd backend

Create a Python virtual environment:

python3 -m venv venv

Activate it on macOS/Linux:

source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Create the local environment file:

cp .env.example .env

Review .env and configure the required local values.

Start FastAPI:

python -m uvicorn app.main:app --reload

The backend should run at:

http://127.0.0.1:8000

FastAPI Swagger documentation:

http://127.0.0.1:8000/docs

Keep this terminal running.

Frontend Setup

Open another terminal.

From the repository root:

cd frontend

Install dependencies:

npm install

Start Vite:

npm run dev

The frontend should run at:

http://localhost:5173

Open that address in your browser.

Running Automated Tests

Enter the backend:

cd backend

Activate the virtual environment if necessary:

source venv/bin/activate

Run:

pytest -q

The backend test suite covers:

Health Check
Authentication
JWT-Protected Endpoints
Job Analysis
Skill Alias Normalization
Overlapping Skill Detection
Evidence Workflow

Example End-to-End Workflow

A typical ProofStack workflow looks like this:

1. Create an account

Email
Password
    ↓
Registration

2. Log in

Credentials
    ↓
JWT

3. Create a project

ProofStack

4. Add evidence

Built authenticated React and FastAPI application

5. Attach skills

React
FastAPI
JWT
Python

6. Generate skill intelligence

ProofStack analyzes the evidence supporting those skills.

7. Analyze a job

Paste a job description containing:

Python
FastAPI
React
JWT
PostgreSQL
Docker
REST API
Git

ProofStack identifies which requirements have evidence and which do not.

8. Ask the assistant

What evidence do I have for FastAPI?

ProofStack retrieves the stored evidence associated with FastAPI.

API Documentation

While the backend is running, interactive API documentation is available through FastAPI Swagger UI:

http://127.0.0.1:8000/docs

This can be used to inspect and test endpoints directly.

Automated Testing Strategy

ProofStack tests important application behavior rather than only individual functions.

Health Testing

Verifies that the API starts and responds.

Authentication Testing

Tests:

Registration
Duplicate Registration
Login
Invalid Password
JWT Generation
Protected Endpoints

Job Analysis Testing

Tests:

Skill Detection
Alias Normalization
Overlapping Aliases
Matched Skills
Missing Skills
Coverage Calculation
Edge Cases

Evidence Workflow Testing

Tests the integrated flow:

Register
   ↓
Login
   ↓
Create Project
   ↓
Create Evidence
   ↓
Attach Skills
   ↓
Retrieve Evidence
   ↓
Generate Intelligence
   ↓
Delete Evidence
   ↓
Confirm Deletion

Security Considerations

ProofStack includes several basic security practices:

Passwords are not stored as plain text.
Authentication uses JWT access tokens.
Protected routes require authentication.
User-specific resources are associated with authenticated users.
Environment configuration is stored outside source control.
.env files are excluded through .gitignore.
Local database files are excluded from Git.
Frontend and backend validation are both used.

The repository contains:

backend/.env.example

as a safe configuration template.

The real:

backend/.env

should never be committed.

Current Development Architecture

The verified local version uses:

React
   ↓
FastAPI
   ↓
SQLAlchemy
   ↓
SQLite

SQLite keeps local development lightweight and allows ProofStack to run without additional database infrastructure.

PostgreSQL and Docker

The repository includes:

docker-compose.yml

as groundwork for a future containerized environment.

A future architecture can use:

React
   ↓
FastAPI
   ↓
SQLAlchemy
   ↓
PostgreSQL

with:

Docker
├── Frontend
├── Backend
└── PostgreSQL

The current verified application runs locally with SQLite, so Docker is not required for the existing version.

Project Evolution

ProofStack was developed progressively across multiple engineering phases.

Phase 1
React ↔ FastAPI
        ↓
Phase 2
POST Requests + Pydantic
        ↓
Phase 3
SQLite Persistence
        ↓
Phase 4
Dashboard
        ↓
Phase 5
CRUD
        ↓
Phase 6
Projects + Skills Relationships
        ↓
Phase 7
Evidence Scoring
        ↓
Phase 8
Skill Intelligence
        ↓
Phase 9
Job Analysis
        ↓
Phase 10
Integrated ProofStack
        ↓
ProofStack 2.0
Authentication + ORM + Testing +
Improved Intelligence Architecture

The GitHub repository contains the polished ProofStack 2.0 application rather than the intermediate learning versions.

Engineering Concepts Demonstrated

ProofStack demonstrates practical experience with:

Frontend Engineering

React state management
Forms
Conditional rendering
REST API communication
Authentication state
Error handling
Responsive interface design

Backend Engineering

REST API design
FastAPI routing
Dependency injection
Pydantic validation
Service-layer architecture
Authentication
Authorization
Error handling

Database Engineering

SQLAlchemy ORM
Relational modeling
One-to-many relationships
Many-to-many relationships
Association tables
User-owned data

Authentication

Password hashing
JWT generation
Bearer authentication
Protected endpoints
User-specific access

Testing

Pytest
API testing
Authentication testing
Integration testing
Regression testing

Applied Intelligence

Evidence scoring
Skill normalization
Job requirement extraction
Evidence coverage
Grounded retrieval

Key Design Principle

ProofStack is based on a simple distinction:

CLAIM

"I know FastAPI."

versus:

EVIDENCE

"I built an authenticated full-stack application
using FastAPI, React, JWT, and Python."

ProofStack structures technical profiles around the second model.

Future Improvements

Potential future improvements include:

PostgreSQL migration
Dockerized deployment
Cloud deployment
GitHub repository integration
Automatic repository evidence extraction
Resume import
Semantic skill extraction
Embedding-based evidence retrieval
LLM-powered grounded assistant
Skill recency tracking
Evidence decay
Public developer profiles
Evidence-backed resume generation

These are planned enhancements and are not presented as implemented functionality in the current version.

Repository Documentation

Additional documentation:

ARCHITECTURE.md — detailed system architecture
RUN_ME_FIRST.md — local setup guidance
backend/tests — automated test suite

Project Status

ProofStack 2.0 — Core application complete

Current verified capabilities:

✓ React frontend
✓ FastAPI backend
✓ REST APIs
✓ SQLAlchemy ORM
✓ SQLite persistence
✓ JWT authentication
✓ Password hashing
✓ User-specific evidence
✓ Projects
✓ Evidence management
✓ Skill relationships
✓ Skill intelligence
✓ Job evidence analysis
✓ Alias normalization
✓ Grounded evidence assistant
✓ Frontend validation
✓ Backend validation
✓ Automated backend tests

Planned:

○ PostgreSQL
○ Dockerized runtime
○ Cloud deployment
○ GitHub integration
○ Semantic retrieval
○ LLM integration

Author

Thejeswar Reddy

GitHub: ThejeswarReddy661

ProofStack

Build proof of what you actually know.

Name		Name	Last commit message	Last commit date
backend		backend
docs/screenshots		docs/screenshots
frontend		frontend
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
README.md		README.md
RUN_ME_FIRST.md		RUN_ME_FIRST.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation

ProofStack 2.0

🌐 Live Application

🚀 Production Architecture

Production Stack

🗄️ Database Environments

✅ Production Deployment Status

Planned Improvements

Evidence-Based Technical Skill Intelligence Platform

Why ProofStack?

Application Preview

Evidence-Based Technical Profile

Projects and Skill Relationships

Skill Intelligence

Job Evidence Analysis

Grounded Evidence Assistant

Core Features

Authentication

Evidence Management

Projects

Skill Intelligence

Job Analyzer

Grounded Assistant

Validation and Error Handling

Automated Testing

Technology Stack

Frontend

Backend

Database

Testing

System Architecture

Relational Data Model

Authentication Flow

Job Analyzer

Skill Alias Normalization

Overlapping Phrase Detection

API Structure

Backend Project Structure

Frontend Project Structure

Running ProofStack Locally

Prerequisites

1. Clone the Repository

Backend Setup

Frontend Setup

Running Automated Tests

Example End-to-End Workflow

1. Create an account

2. Log in

3. Create a project

4. Add evidence

5. Attach skills

6. Generate skill intelligence

7. Analyze a job

8. Ask the assistant

API Documentation

Automated Testing Strategy

Health Testing

Authentication Testing

Job Analysis Testing

Evidence Workflow Testing

Security Considerations

Current Development Architecture

PostgreSQL and Docker

Project Evolution

Engineering Concepts Demonstrated

Frontend Engineering

Backend Engineering

Database Engineering

Authentication

Testing

Applied Intelligence

Key Design Principle

Future Improvements

Repository Documentation

Project Status

Author

ProofStack