Archon Frontend

A modern, feature-rich frontend for Archon — an autonomous AI coding agent designed to assist developers over extended periods with persistent memory, intelligent planning, and repository-level understanding.

🚀 Overview

Archon Frontend is a Next.js-based web application that provides an intuitive interface for:

Authentication & Profile Management — Secure user authentication with JWT tokens
Project Management — Create, manage, and organize coding projects
AI-Powered Chat — Real-time conversations with the AI agent
Agent Management — Configure and monitor autonomous agents working on your projects
Context & Memory — Upload project files and maintain persistent context
Planning & Tasks — AI-assisted feature planning and autonomous task execution

This frontend connects to the Archon backend API (Django/DRF) to provide a seamless development experience.

✨ Features

🔐 Secure Authentication — JWT-based authentication with refresh token support
💬 Real-time Chat — WebSocket-powered messaging with the AI agent
🤖 Agent Management — Create, configure, and monitor autonomous AI agents
📁 Project Context — Upload and manage project files for contextual AI assistance
📝 Planning Tools — Break down features into tasks with autonomous execution
💾 Memory System — Persistent memory and context across sessions
🎨 Dark/Light Mode — Theme switching with system preference detection
📱 Responsive Design — Fully responsive UI using TailwindCSS
✅ Type-Safe — Built with TypeScript for enhanced development experience
🧭 Features Overview Page — Public technical walkthrough at /features with architecture diagrams, Mermaid workflow charts, and product screenshots

🧭 Features Overview Page

The frontend includes a dedicated features page to explain how Archon works end-to-end:

Route: /features
Entry points: linked from both landing page (/) and login page (/login)
Purpose: explain architecture, multi-agent workflow, RAG memory model, tooling, and shipped UI capabilities in one place
Assets: screenshots rendered from public/archon-ss

Workflow Markup Used on the Page

User Request
   -> API/WebSocket ingress
   -> Master Orchestrator
   -> Planner + Executor
   -> Context + Vector Search
   -> Memory (STM/LTM)
   -> Response + Realtime Progress

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js — Version 18.x or higher
npm or yarn — Package manager
Git — Version control
Backend API — The Archon backend must be running

Optional:

Docker — For containerized deployment

🛠️ Installation

1. Clone the Repository

git clone https://github.com/IamSadik/Archon-Frontend.git
cd Archon-Frontend

2. Install Dependencies

npm install
# or
yarn install

3. Configure Environment Variables

Create a .env.local file in the root directory:

# Backend API Configuration
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_WS_BASE_URL=ws://localhost:8000

# Optional: Add other environment variables as needed

Important:

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser
Keep sensitive tokens in server-only environment variables
Never commit .env.local to version control

4. Run Development Server

npm run dev
# or
yarn dev

The application will be available at http://localhost:3000

📦 Building & Deployment

Local Build

npm run build
npm start

Deployment on Render

Connect Repository — Link your GitHub repository to Render
Configure Build Command — Use npm run build
Configure Start Command — Use npm start
Set Environment Variables — Add NEXT_PUBLIC_API_BASE_URL and NEXT_PUBLIC_WS_BASE_URL in Render dashboard
Deploy — Render will automatically build and deploy

Key Notes:

.next and node_modules are automatically excluded (in .gitignore)
Render will install dependencies and build the project on every deploy
Ensure the backend API endpoint is accessible from Render

Docker Deployment

# Build image
docker build -t archon-frontend .

# Run container
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_BASE_URL=https://api.example.com \
  archon-frontend

📁 Project Structure

src/
├── app/                          # Next.js 14 app directory
│   ├── layout.tsx               # Root layout
│   ├── page.tsx                 # Home page
│   ├── (auth)/                  # Authentication routes (nested layout)
│   │   ├── login/               # Login page
│   │   ├── register/            # Registration page
│   │   └── forgot-password/     # Password recovery
│   ├── (dashboard)/             # Dashboard routes (protected)
│   │   ├── chat/                # Chat interface
│   │   ├── dashboard/           # Main dashboard
│   │   ├── projects/            # Project management
│   │   ├── agents/              # Agent management
│   │   ├── planning/            # Planning & tasks
│   │   ├── memory/              # Memory management
│   │   ├── context/             # Context management
│   │   ├── profile/             # User profile
│   │   └── settings/            # User settings
│   └── api/                     # API route handlers (if needed)
├── components/
│   ├── ui/                      # Reusable UI components
│   ├── chat/                    # Chat-specific components
│   ├── projects/                # Project management components
│   ├── context/                 # Context management components
│   ├── planning/                # Planning UI components
│   └── [feature]/               # Feature-specific components
├── hooks/                       # Custom React hooks
│   ├── useAuth.ts              # Authentication logic
│   ├── useChat.ts              # Chat functionality
│   ├── useProjects.ts          # Project management
│   ├── useAgents.ts            # Agent management
│   ├── usePlanning.ts          # Planning functionality
│   └── ...
├── services/                    # API service layer
│   ├── auth.service.ts         # Authentication API
│   ├── chat.service.ts         # Chat API
│   ├── project.service.ts      # Project API
│   ├── agent.service.ts        # Agent API
│   └── ...
├── lib/                        # Utility functions
│   ├── api.ts                  # API client setup
│   ├── utils.ts                # Helper functions
│   ├── websocket.ts            # WebSocket management
│   └── ...
├── store/                      # Zustand state management
│   └── useAuthStore.ts         # Auth state
├── types/                      # TypeScript type definitions
│   └── index.ts
└── styles/                     # Global styles

🔌 API Integration

The frontend communicates with the Archon backend via:

REST API — Standard HTTP endpoints for CRUD operations
WebSocket — Real-time communication for chat and live updates

Example: Authentication Flow

// Login
const response = await authService.login(email, password);
// Response: { access: "token", refresh: "token", user: {...} }

// Store tokens
localStorage.setItem("access_token", response.access);
localStorage.setItem("refresh_token", response.refresh);

// Use in subsequent requests
// Authorization header: "Bearer {access_token}"

See API_DOCUMENTATION.md for complete API reference.

🎨 Technologies & Libraries

Core Framework

Next.js 14 — React framework with App Router
React 18 — UI library
TypeScript — Type-safe JavaScript

Styling & UI

TailwindCSS — Utility-first CSS
Radix UI — Headless UI components
Lucide React — Icon library
Framer Motion — Animation library

State Management & Data Fetching

React Query (TanStack Query) — Server state management
Zustand — Client state management
React Hook Form — Form state management

API & Communication

Axios — HTTP client
Socket.io — Real-time communication

Utilities

date-fns — Date manipulation
zod — Schema validation
clsx — Conditional className utility
react-markdown — Markdown rendering

Development Tools

Jest — Testing framework
ESLint — Code linting
Prettier — Code formatting

🔐 Environment Variables

Variable	Description	Example
`NEXT_PUBLIC_API_BASE_URL`	Backend API base URL	`http://localhost:8000`
`NEXT_PUBLIC_WS_BASE_URL`	WebSocket server URL	`ws://localhost:8000`

🧪 Testing

Run tests with:

npm run test              # Run tests once
npm run test:watch       # Run tests in watch mode

Tests are located in the __tests__/ directory.

📝 Scripts

Command	Description
`npm run dev`	Start development server
`npm run build`	Build for production
`npm start`	Start production server
`npm run lint`	Run ESLint
`npm test`	Run tests (single run)
`npm run test:watch`	Run tests in watch mode

🔄 Development Workflow

1. Creating a New Feature

# Create feature branch
git checkout -b feature/feature-name

# Make changes, test locally
npm run dev

# Run linter
npm run lint

# Commit changes
git add .
git commit -m "feat: description of changes"

# Push to branch
git push origin feature/feature-name

2. Debugging

Use React DevTools browser extension
Check console for API errors
Use Network tab to inspect API calls
Enable debug logging in services

3. Performance Optimization

Use dynamic imports for large components
Optimize images with Next.js Image component
Monitor bundle size with next/bundle-analyzer

🚀 Deployment Checklist

Before deploying to production:

Environment variables configured
Backend API endpoint is correct
Build completes without errors (npm run build)
Tests pass (npm test)
Linter passes (npm run lint)
No console errors in development
Responsive design tested on mobile
Authentication flow tested end-to-end

🐛 Troubleshooting

Build Fails with Module Not Found

# Clear cache and reinstall
rm -rf node_modules .next
npm install
npm run build

API Connection Issues

Verify NEXT_PUBLIC_API_BASE_URL is correct
Check backend API is running
Verify CORS configuration on backend
Check network tab in browser DevTools

WebSocket Connection Issues

Verify NEXT_PUBLIC_WS_BASE_URL is correct
Ensure backend supports WebSocket
Check firewall/proxy settings
Look for connection error logs in console

Authentication Issues

Verify JWT tokens are in localStorage
Check token expiration
Try logging out and back in
Clear browser cache and localStorage

📚 Additional Resources

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is part of the Archon ecosystem. See LICENSE file for details.

👤 Author

IamSadik — GitHub Profile

📞 Support

For issues, questions, or suggestions:

Open an issue on GitHub Issues
Check existing documentation in API_DOCUMENTATION.md
Review the project structure for guidance

Last Updated: May 6, 2026

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
public		public
src		src
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
API_DOCUMENTATION.md		API_DOCUMENTATION.md
Dockerfile		Dockerfile
README.md		README.md
next-env.d.ts		next-env.d.ts
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo

Folders and files

Latest commit

History

Repository files navigation