🧠 DeepStack AI Engineering Practice

A multi-language, multi-agent experimental monorepo targeting a 2026 production-grade architecture.

This repository serves as an AI-assisted engineering practice ground — combining bleeding-edge frontend tooling, enterprise Java on virtual threads, and Solana blockchain integration — all orchestrated through an agentic Cline workspace.

---

🚀 Project Vision

DeepStack is a polyglot monorepo designed to validate and refine an AI-first development workflow. It spans the full modern stack:

• A Next.js 16 client with React 19 Compiler optimizations and Solana Web3.js wallet integration
• A Spring Boot 4 backend on Java 25 (LTS) with virtual threads and a Solana Devnet observer
• PostgreSQL 16 database via Docker, with JPA/Hibernate entity mapping
• Solana on-chain programs written in Rust/Anchor

The project is structured as a research sandbox for agentic code generation, MCP tooling, and architectural pattern enforcement — with strict linting, zero-warning builds, and persona-driven subagents.

---

🛠️ 2026 Tech Stack

Layer	Technology
Frontend	Next.js 16 (App Router) · React 19 · TypeScript 5.7 · Tailwind CSS 4 · Turbopack · Solana Wallet Adapter
Backend	Java 25 (LTS) · Spring Boot 4.x · Maven · Virtual Threads (Project Loom)
Database	PostgreSQL 16 (Docker) · Spring Data JPA · Hibernate 7.x
Blockchain	Solana Devnet · Web3.js · JDK HttpClient RPC client
Contract	Solana · Rust · Anchor
Orchestration	Cline (AI agent) · MCP (Model Context Protocol) · Claude

---

🎭 Agentic Architecture

The workspace defines specialized subagent personas in .claude/agents/. Each agent is a self-contained persona with domain-specific rules, constraints, and context isolation.

Available Agents

Agent	Specialty	Boundary
@ui-engineer	Next.js 16 + React 19 + Tailwind CSS 4 components + Solana wallet	frontend/
@backend-architect	Java 25 + Spring Boot 4.x services, JPA repositories, Solana RPC	backend/
@solana-expert	Rust/Anchor programs, accounts, and instruction handlers	solana/

How to Summon

Mention the agent's handle in any prompt:

@ui-engineer Create a data-table component with sorting and pagination.

The system automatically adopts the corresponding persona, strict ruleset, and context boundary — preventing cross-contamination between frontend, backend, and Solana concerns.

---

📂 Project Structure

.
├── .clinerules                  # Master project memory & workflow rules
├── .claude/
│   ├── agents/                  # Subagent persona definitions
│   │   ├── ui-engineer.md
│   │   ├── backend-architect.md
│   │   └── solana-expert.md
│   └── skills/                  # Reusable audit/analysis skills
│       └── code-critic.md
│
├── frontend/                    # Next.js 16 App Router client
│   ├── src/
│   │   ├── app/                 # Pages, layouts, API routes
│   │   ├── components/
│   │   │   ├── ui/              # Reusable primitives (Button, etc.)
│   │   │   └── features/        # Domain components (Wallet, Memo, Theme)
│   │   └── lib/                 # Server actions, utilities
│   ├── package.json
│   ├── tsconfig.json
│   ├── next.config.ts
│   └── tailwind.config.ts
│
├── backend/                     # Java 25 + Spring Boot 4.x
│   ├── src/main/java/com/claudepractice/api/
│   │   ├── controllers/         # REST API endpoints (Health, Wallets)
│   │   ├── services/            # Business logic (RPC, Observers, Registry)
│   │   ├── repositories/        # JPA data access layer
│   │   ├── model/               # JPA entities (TransactionEntity)
│   │   └── dto/                 # Java record DTOs (HealthResponse, RegisterWalletRequest)
│   └── src/main/resources/      # application.yml, application.properties
│
├── solana/                      # Solana Rust/Anchor programs
│   ├── programs/<name>/src/     # Smart contract logic
│   ├── tests/                   # TypeScript integration tests
│   └── migrations/              # Deployment scripts
│
├── docker-compose.yml           # PostgreSQL 16 container
├── CLAUDE.md                    # (Per-directory rules files)
├── PROGRESS.md                  # Sprint tracking & milestone log
└── README.md                    # This file

---

✅ Current Status

Session 10 — Solana-Java-Postgres Bridge — Complete 🎉

• Infrastructure: Dockerized PostgreSQL 16 with custom roles, auto-provisioned transactions table via Hibernate ddl-auto: update
• Backend — Solana Observer:
  • SolanaRpcClient — JDK HttpClient-based RPC client to Solana Devnet using Java 25 virtual threads
  • SolanaObserverService — polls registered wallet addresses every 15s, fetches signatures, extracts transaction details, persists to PostgreSQL
  • WalletRegistryService — thread-safe ConcurrentHashMap-backed registry for dynamic multi-user wallet observation
• REST API — Dynamic Wallet Registration:
  • POST /api/v1/wallets/active — register a wallet address (201 CREATED)
  • DELETE /api/v1/wallets/active — unregister a wallet address (200 OK)
  • GET /api/v1/wallets/active — list all active wallet addresses
  • No hardcoded wallet addresses — purely dynamic, frontend-driven registration
• Frontend — Solana Integration:
  • SolanaWalletProvider with ConnectionProvider, WalletProvider, WalletModalProvider
  • WalletRegistrar — auto-registers connected wallet with backend via POST /api/v1/wallets/active
  • SendMemoButton — constructs and sends a Solana memo transaction using @solana-program/memo
  • Header — wallet connect button with SOL balance display
  • Hydration mismatch fixed via dynamic import with ssr: false
• Live Verification: Observer detected and saved Devnet transactions to PostgreSQL — E2E flow validated

Agentic Documentation Architecture — Complete

• Hybrid AGENTS.md monorepo standard established:
  • AGENTS.md (root) — global multi-agent governance, domain boundaries, persona references, summoning protocol
  • frontend/AGENTS.md — frontend-only rules (RSC, TypeScript, Tailwind, Shadcn UI, component hierarchy)
  • backend/AGENTS.md — backend-only rules (Java 25/Spring Boot 4: strict layering, DTOs as records, virtual threads, SLF4J, API contracts)
• .clinerules references updated from frontend/AGENTS.md → AGENTS.md (root)
• Clean separation of concerns: global governance at root, domain-specific rules in sub-project folders

Backend Foundation — Complete

• Java 25 / Spring Boot 4.x backend initialized with Maven wrapper
• Virtual threads enabled (spring.threads.virtual.enabled=true) for Java 25 Loom
• Health endpoint at GET /api/v1/health returning {"status":"UP","engine":"Java 25 / Spring Boot 4"}
• PostgreSQL 16 connected via Spring Data JPA + Hibernate 7.x

Green Build — Achieved

Both mvn clean compile (Java) and next build (TypeScript) compile with zero errors.

Sprint Progress

• Sessions 1–10 — ✅ Complete (Bootstrapping through Solana-Java-Postgres Bridge)

---

🚀 Getting Started

Prerequisites

• Docker Desktop (for PostgreSQL)
• Java 25 JDK
• Node.js 22+
• A browser wallet like Phantom (for Solana Devnet interaction)

1. Start the Database

docker compose up -d

This starts PostgreSQL 16 on port 5432 with database claudepractice, user claudepractice.

2. Start the Backend (Spring Boot 4)

Open a terminal at the project root:

cd backend
.\mvnw.cmd spring-boot:run

The server starts on http://localhost:8080.

Verify health:

curl http://localhost:8080/api/v1/health
# → {"status":"UP","engine":"Java 25 / Spring Boot 4"}

3. Start the Frontend (Next.js 16)

Open a separate terminal:

cd frontend
npm run dev

The dev server starts on http://localhost:3000 with Turbopack.

4. Connect Your Wallet

1. Open http://localhost:3000 in your browser
2. Click "Connect Wallet" in the header
3. Approve the connection in Phantom (or your Solana wallet)
4. The frontend automatically registers your wallet with the backend:

   POST /api/v1/wallets/active  { "address": "your_wallet_address" }
   

   You'll see [WALLET-REGISTRAR] ✅ Registered wallet with backend in the browser console.

5. Send a Memo Transaction

1. Click "Send Memo" button
2. Approve the transaction in your wallet
3. Watch the backend terminal for detection:

   [SOLANA-OBSERVER] 🟢 Transaction verified and saved: {signature} (owner=..., amount=... lamports)
   

4. Verify in the database:

   docker exec claudepractice-db psql -U claudepractice -d claudepractice \
     -c "SELECT * FROM transactions;"

Quick Reference

# Kill stale Java processes (if port 8080 is in use)
Get-Process -Name java | Stop-Process -Force

# Start backend with dynamic wallet registry (no env var needed)
cd backend; .\mvnw.cmd spring-boot:run

# Start frontend
cd frontend; npm run dev

# Query PostgreSQL
docker exec -it claudepractice-db psql -U claudepractice -d claudepractice

# List active wallet addresses being watched
curl http://localhost:8080/api/v1/wallets/active

---

📄 License

Private — experimental research sandbox for AI-assisted engineering practices.