Trading Journal

A self-hosted trading journal application for equity futures traders with playbook management, trade recording, and analytics.

Features

• User Authentication: Simple username-based authentication (no passwords)
• Playbook Management: Create and manage trading playbooks with entry/exit criteria
• Trade Recording: Record trade entries and exits with screenshots and criteria tracking
• Dashboard: View summary statistics and recent trade activity
• Reports & Analytics: Analyze trading performance with metrics like win rate, P&L, and mean time in trade
• Screenshot Support: Paste screenshots directly from clipboard
• Self-Hosted: Runs locally with SQLite database

Tech Stack

• Backend: Go 1.21+ with chi router
• Frontend: HTMX with Go html/template
• Database: SQLite with WAL mode
• Session Management: gorilla/sessions

Quick Start

Prerequisites

• Go 1.21 or higher
• Make (optional, for using Makefile commands)

Local Development

1. Clone the repository:

cd trading-journal

2. Install dependencies:

go mod download

3. Run the application:

make run
# or
go run cmd/server/main.go

4. Open your browser and navigate to:

http://localhost:8080

5. Login with any username (account will be created automatically)

Using Docker

1. Build and run with Docker Compose:

make docker-build
make docker-run

2. Access the application at http://localhost:8080

3. Stop the containers:

make docker-stop

Configuration

The application can be configured using environment variables:

• PORT: Server port (default: 8080)
• DB_PATH: Path to SQLite database file (default: ./data/trading-journal.db)
• SESSION_SECRET: Secret key for session encryption (default: change-this-in-production)

Usage

Creating a Playbook

1. Navigate to Playbooks in the navigation menu
2. Click Create Playbook
3. Enter a playbook name
4. Add entry criteria (conditions that must be met to enter a trade)
5. Add exit criteria (conditions that must be met to exit a trade)
6. Click Create Playbook

Recording a Trade Entry

1. Navigate to New Trade in the navigation menu
2. Select a playbook
3. Enter trade details:
   • Product traded (e.g., ES, NQ, CL)
   • Capital used
   • Entry date and time
   • Check which entry criteria were met
4. Optional: Paste a screenshot (Cmd+Shift+4 on Mac, Win+Shift+S on Windows, then click Paste)
5. Click Record Entry

Closing a Trade

1. Navigate to Open Trades
2. Click Close Trade for the trade you want to exit
3. Enter exit details:
   • Exit date and time
   • Profit/Loss (use negative for losses)
   • Check which exit criteria were met
4. Optional: Paste exit screenshot
5. Click Close Trade

Viewing Reports

1. Navigate to Reports in the navigation menu
2. Select a time period to filter trades
3. View metrics:
   • Total trades
   • Total P&L
   • Win rate
   • Average P&L per trade
   • Mean time in trade
   • Winning/losing trades breakdown

Database Backup

The application uses SQLite, so backing up is simple:

1. Stop the application
2. Copy the database file:

cp data/trading-journal.db data/trading-journal-backup-$(date +%Y%m%d).db

For Docker:

docker-compose down
cp data/trading-journal.db data/trading-journal-backup-$(date +%Y%m%d).db
docker-compose up -d

Project Structure

trading-journal/
├── cmd/server/           # Application entry point
│   └── main.go
├── internal/
│   ├── auth/            # Authentication & session management
│   ├── database/        # Database connection & migrations
│   ├── handlers/        # HTTP handlers
│   ├── models/          # Data models
│   ├── services/        # Business logic
│   └── templates/       # HTML templates
├── web/static/          # CSS, JavaScript
├── migrations/          # SQL migration files
├── data/               # SQLite database (created at runtime)
├── Dockerfile
├── docker-compose.yml
└── Makefile

Development

VS Code Integration

The project includes complete VS Code configuration for a streamlined development experience:

Quick Start:

1. Open the project in VS Code
2. Install recommended extensions (when prompted)
3. Press Ctrl+Shift+B to build
4. Press F5 to start debugging

Available Tasks (access via Ctrl+Shift+B or Terminal → Run Task):

• Run Trading Journal - Quick start with go run
• Build Trading Journal - Compile binary
• Build and Run - Build then execute
• Test Trading Journal - Run all tests
• Docker Build/Run/Stop - Docker workflow
• Clean Build Artifacts - Fresh start
• View Database - Inspect SQLite database

Debug Configurations:

• Launch Trading Journal (standard run)
• Debug Trading Journal (with breakpoints)
• Attach to Running Process

See .vscode/README.md for detailed documentation.

Running Tests

make test
# or
go test -v ./...
# or use VS Code task: "Test Trading Journal"

Building Binary

make build
# or
go build -o bin/trading-journal cmd/server/main.go
# or use VS Code: Ctrl+Shift+B

Code Structure

The application follows a three-layer architecture:

1. Handlers: HTTP request handling and response rendering
2. Services: Business logic and database operations
3. Database: Connection management and migrations

Security Considerations

• Username-only authentication (no passwords) - suitable for single-user or trusted environments
• Session data stored in encrypted cookies (HttpOnly, SameSite)
• SQL injection prevention via parameterized queries
• XSS protection via Go's html/template auto-escaping
• User data isolation (all queries filtered by user_id)
• Screenshot size limit: 5MB per image

Troubleshooting

Database locked error

If you see "database is locked" errors:

• Ensure only one instance is running
• WAL mode is enabled by default for better concurrency

Port already in use

Change the port using the PORT environment variable:

PORT=3000 make run

Screenshots not pasting

1. Ensure you've copied a screenshot to clipboard
2. On Mac: Cmd+Shift+4 (select area)
3. On Windows: Win+Shift+S
4. Click the "Paste Screenshot" button or press Ctrl+V

License

MIT License - Feel free to use this for personal or commercial projects.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

Potential future enhancements:

• Export reports to CSV/PDF
• Trade tags and notes
• Multiple screenshot support per trade
• Chart integration
• Trade journal (daily notes)
• Performance statistics by playbook
• Email notifications for open trades

Support

For issues or questions, please open an issue on GitHub.