# 🚀 Quick Start Guide
Get your Architectural Decision Log system up and running in minutes!
## Prerequisites
- **Node.js 18+** (Check: `node --version`)
- **npm** (Comes with Node.js)
- **Git** (Optional, for version control)
## Installation
### Step 1: Install Dependencies
```bash
npm install
```
This will install all required packages for the GraphQL backend, MCP server, and UI.
### Step 2: Start the System
```bash
npm start
```
This starts both the GraphQL server and the Web UI.
**Expected Output:**
```
🚀 Starting ADL System...
🚀 GraphQL Server ready at: http://localhost:4000/graphql
🌐 UI Server running at: http://localhost:3000
✅ All services started!
```
### Step 3: Access the Application
Open your browser and navigate to:
- **Web UI**: http://localhost:3000
- **GraphQL Playground**: http://localhost:4000/graphql
## First-Time Setup
### Load Sample Data (Optional)
To see the system in action with example architectural decisions:
1. Make sure the GraphQL server is running
2. In a new terminal, run:
```bash
npm run load-sample-data
```
This will create 10 sample ADL entries.
## Basic Usage
### Via Web UI
1. **View Entries**: Open http://localhost:3000
2. **Create Entry**: Click "➕ New Decision"
3. **Edit Entry**: Click "Edit" on any row
4. **Delete Entry**: Click "Delete" on any row
### Via GraphQL Playground
1. Open http://localhost:4000/graphql
2. Try this query:
```graphql
query {
adlEntries {
id
title
author
status
}
}
```
3. Create an entry:
```graphql
mutation {
createADLEntry(input: {
author: "Your Name"
title: "My First Decision"
decision: "This is my first architectural decision"
factSheets: ["Example Sheet"]
status: Proposed
}) {
id
title
}
}
```
## MCP Server Setup
To use the ADL system with MCP clients (like Claude Desktop):
### 1. Start GraphQL Server
```bash
npm run start:graphql
```
### 2. Configure Your MCP Client
Add to your MCP client configuration:
```json
{
"mcpServers": {
"adl": {
"command": "node",
"args": ["C:/Users/dk123/source/ADL/mcp-server/server.js"],
"env": {
"GRAPHQL_URL": "http://localhost:4000/graphql"
}
}
}
}
```
**Note**: Replace the path with your actual project path.
### 3. Use MCP Tools
In your MCP client (e.g., Claude Desktop):
- "List all ADL entries"
- "Create a new ADL entry for using Kubernetes"
- "Update entry [id] to Approved status"
## Stopping the System
Press `Ctrl+C` in the terminal where `npm start` is running.
On Linux, you can also use:
```bash
./stop.sh
```
## Common Issues
### Port Already in Use
If you see "Port 4000 is already in use":
**Windows:**
```powershell
netstat -ano | findstr :4000
taskkill /PID <PID> /F
```
**Linux/Mac:**
```bash
lsof -ti:4000 | xargs kill -9
```
### Cannot Find Module
If you see module errors:
```bash
rm -rf node_modules package-lock.json
npm install
```
### GraphQL Server Not Responding
1. Check if it's running: `curl http://localhost:4000/graphql`
2. Check the terminal for error messages
3. Restart: `npm run start:graphql`
## Next Steps
1. **Read the Documentation**
- [README.md](README.md) - Overview and features
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
- [TESTING.md](TESTING.md) - Testing guide
2. **Deploy to Linux**
- See [INSTALL-LINUX.md](INSTALL-LINUX.md)
3. **Customize**
- Modify GraphQL schema in `backend/schema.js`
- Update UI in `ui/index.html`
- Add new MCP tools in `mcp-server/server.js`
## Docker Quick Start
If you prefer Docker:
```bash
# Build and start
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down
```
Access the application at:
- UI: http://localhost:3000
- GraphQL: http://localhost:4000/graphql
## File Structure
```
ADL/
├── backend/ # GraphQL server
├── mcp-server/ # MCP server
├── ui/ # Web interface
├── scripts/ # Utility scripts
├── data/ # SQLite database (auto-created)
└── package.json # Dependencies
```
## Support
- **Issues**: Create an issue on GitHub
- **Email**: dk123579@gmail.com
- **Documentation**: See README.md and other .md files
## What You Can Do
✅ Create architectural decisions
✅ Track decision status (Proposed/Approved)
✅ Link decisions to SAP/LeanIX fact sheets
✅ View decisions in a table format
✅ Access via Web UI, GraphQL API, or MCP
✅ Run on Windows, Linux, or macOS
✅ Deploy with Docker
## Development Mode
To run all services with auto-reload:
```bash
npm run dev
```
This runs:
- GraphQL server on port 4000
- MCP server on stdio
- UI server on port 3000
## Environment Variables
Create a `.env` file (optional):
```bash
GRAPHQL_PORT=4000
UI_PORT=3000
NODE_ENV=development
```
## Data Location
Your ADL entries are stored in:
```
data/adl.sqlite
```
**Backup**: `cp data/adl.sqlite data/backup.sqlite`
## Congratulations! 🎉
You now have a fully functional Architectural Decision Log system!
Start creating your first architectural decision and track your technical choices effectively.
---
**Need Help?** Check [TESTING.md](TESTING.md) for troubleshooting or open an issue on GitHub.
