Skip to content

Commit 1532b03

Browse files
nickytonlinenickytonline
committed
docs: add CLAUDE.md for project guidance and architecture overview
1 parent bee646a commit 1532b03

1 file changed

Lines changed: 157 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
This is the **Pomerium MCP Chat Demo** - a minimal chat application showcasing remote Model Context Protocol (MCP) servers secured with Pomerium. The application demonstrates how to build internal applications that use agentic frameworks and LLM APIs with MCP server integration.
8+
9+
## Technology Stack
10+
11+
- **Frontend**: React 19 with TypeScript in strict mode
12+
- **Framework**: TanStack Start (SSR routing with file-based patterns)
13+
- **Styling**: Tailwind CSS 4.0 + Shadcn/ui components
14+
- **Validation**: Zod for runtime validation and TypeScript integration
15+
- **State Management**: React Query (TanStack Query) for server state, React Context for global state
16+
- **Build Tool**: Vite 6.3
17+
- **Testing**: Vitest with jsdom environment
18+
- **Documentation**: Storybook for component documentation
19+
20+
## Development Commands
21+
22+
```bash
23+
# Development server with hot reloading
24+
npm run dev
25+
26+
# Production build
27+
npm run build
28+
29+
# Start production server
30+
npm run start
31+
32+
# Testing
33+
npm run test # Run tests once
34+
npm run test:ci # Run tests with coverage
35+
36+
# Code quality
37+
npm run lint # ESLint check
38+
npm run format # Prettier format
39+
npm run format:check # Check formatting and linting
40+
41+
# Storybook
42+
npm run storybook # Development Storybook server
43+
npm run build-storybook # Build Storybook for production
44+
```
45+
46+
## Architecture Overview
47+
48+
### Routing Pattern (TanStack Start)
49+
- **File-based routing** in `src/routes/`
50+
- **Client routes**: `.tsx` files with `createFileRoute()`
51+
- **Server routes**: `.ts` files in `src/routes/api/` with `createServerFileRoute()`
52+
- All routes must include `errorBoundary` and `pendingBoundary` for proper error/loading handling
53+
54+
### State Management Strategy
55+
- **Route Loaders**: For initial page data, SSR requirements, and critical path data
56+
- **React Query**: For dynamic/optional data, mutations, and client-side updates
57+
- **React Context**: For global application state (user, theme, etc.)
58+
59+
### Component Architecture
60+
- **UI Components**: Primarily Shadcn/ui components in `src/components/ui/`
61+
- **Custom Components**: Application-specific components in `src/components/`
62+
- **Storybook Stories**: Every component must have a colocated `.stories.tsx` file
63+
- **Tests**: Components should have `.test.tsx` files using Vitest + Testing Library
64+
65+
### Data Validation
66+
- **Zod schemas** defined in `src/lib/schemas.ts`
67+
- Validate all external data: API responses, user input, environment variables
68+
- Use `.safeParse()` for robust error handling
69+
70+
## MCP Integration Patterns
71+
72+
### MCP Client Application
73+
This app runs as an MCP client behind Pomerium with `mcp.client: {}` configuration. Key patterns:
74+
75+
1. **Server Discovery**: Use `/.pomerium/mcp/routes` endpoint to get available MCP servers
76+
2. **Authentication Flow**: Direct users to `/.pomerium/mcp/connect` for upstream OAuth when needed
77+
3. **Tool Calls**: Pass the external token to LLM APIs for MCP server access
78+
4. **User Identity**: Read `X-Pomerium-Assertion` header for user claims
79+
80+
### Key MCP Features
81+
- **Chat Interface**: AI-powered chat using OpenAI with tool calling capabilities
82+
- **Server Management**: Dynamic server selection and connection status
83+
- **Tool Toggles**: Enable/disable specific tools (code interpreter, web search, etc.)
84+
- **Model Selection**: Support for different OpenAI models
85+
86+
## File Organization Conventions
87+
88+
### Import Patterns
89+
Always use `@/` alias for internal imports:
90+
```typescript
91+
// ✅ Good
92+
import { Button } from '@/components/ui/button'
93+
import { userSchema } from '@/lib/schemas'
94+
95+
// ❌ Bad
96+
import { Button } from '../components/ui/button'
97+
```
98+
99+
### Directory Structure
100+
```
101+
src/
102+
├── components/ # Shared UI components
103+
│ └── ui/ # Shadcn/ui components
104+
├── contexts/ # React Context providers
105+
├── hooks/ # Custom React hooks
106+
├── lib/ # Utilities and schemas
107+
├── mcp/ # MCP client integration
108+
├── routes/ # TanStack Start routes
109+
│ └── api/ # Server routes (.ts files)
110+
└── styles.css # Global Tailwind styles
111+
```
112+
113+
## Code Quality Standards
114+
115+
### TypeScript
116+
- **Strict mode enabled** - never use `any` type
117+
- Use proper generics and type inference
118+
- Validate external data with Zod schemas
119+
120+
### Component Patterns
121+
- **Function components only** with proper TypeScript interfaces
122+
- **Accessibility first** - include ARIA attributes and semantic HTML
123+
- **Error boundaries** and loading states in all routes
124+
- **Mobile-first responsive design** with Tailwind
125+
126+
### Testing Requirements
127+
- Component tests using Vitest + Testing Library
128+
- Storybook stories for all custom components
129+
- Focus on user interactions and accessibility
130+
131+
## Important Development Notes
132+
133+
- **Shadcn Components**: Add new components with `npx shadcn@latest add <component-name>`
134+
- **Environment**: Uses Docker Compose setup with Pomerium for full MCP functionality
135+
- **Authentication**: Integrated with Pomerium OAuth2 flows
136+
- **Audit Logging**: MCP tool calls are logged for monitoring and compliance
137+
138+
## Pomerium MCP Configuration
139+
140+
The application expects specific Pomerium route configuration:
141+
142+
```yaml
143+
# Client route (this app)
144+
- from: https://mcp-app-demo.your-domain.com
145+
to: http://mcp-app-demo:3000
146+
mcp:
147+
client: {}
148+
149+
# Server routes (MCP servers)
150+
- from: https://mcp-server.your-domain.com
151+
to: http://mcp-server:8080/mcp
152+
name: "Server Name"
153+
mcp:
154+
server: {}
155+
```
156+
157+
This configuration enables the app to discover MCP servers and handle authentication flows seamlessly.

0 commit comments

Comments
 (0)