Engineering Memory OS

• Hackathon event: CockroachDB × AWS
• Hackathon submission: Engineering Memory OS

Engineering Memory OS is a local-first engineering workspace built with React, FastAPI, CockroachDB, and Redis. The project is containerized using Docker and supports separate development and production configurations through Docker Compose.

Tech Stack

• Frontend: React + Vite + TypeScript + Tailwind CSS
• Backend: FastAPI
• Database: CockroachDB
• Cache: Redis
• Containerization: Docker & Docker Compose
• Reverse Proxy (Production): Nginx

Project Structure

.
├── backend/
│   ├── app/
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/
│   ├── src/
│   ├── Dockerfile
│   ├── package.json
│   └── pnpm-lock.yaml
│
├── nginx/
│   └── nginx.conf
│
├── docker-compose-dev.yaml
├── docker-compose-prod.yaml
└── README.md

Requirements

• Docker
• Docker Compose (v2)
• Docker Buildx

Verify installation:

docker --version
docker compose version
docker buildx version

Development

Start the development environment:

docker compose -f docker-compose-dev.yaml up --build

Stop the environment:

docker compose -f docker-compose-dev.yaml down

Rebuild containers:

docker compose -f docker-compose-dev.yaml up --build

Development Services

Service	URL
Frontend	http://localhost:5173
FastAPI	http://localhost:8000
Swagger UI	http://localhost:8000/docs
CockroachDB Admin	http://localhost:8080
Cockroach SQL	localhost:26257
Redis	localhost:6379

Production

Build and start:

docker compose -f docker-compose-prod.yaml up --build -d

Stop:

docker compose -f docker-compose-prod.yaml down

Useful Commands

View running containers:

docker compose ps

View logs:

docker compose logs

Follow logs:

docker compose logs -f

Restart a service:

docker compose restart backend

Rebuild a single service:

docker compose build backend

Open a shell inside a container:

docker compose exec backend bash

or

docker compose exec frontend sh

Stop and remove containers:

docker compose down

Remove containers, networks, and volumes:

docker compose down -v

Environment Variables

Backend services use environment variables provided through Docker Compose.

Typical variables include:

DATABASE_URL=
REDIS_URL=

Health Check

The frontend displays the health of:

• FastAPI server
• CockroachDB
• Redis

The backend should expose:

GET /health

Example response:

{
  "server": true,
  "database": true,
  "redis": true
}