Skip to content

Commit 6695544

Browse files
CopilotketanMehtaa
Copilot
and
ketanMehtaa
committed
Add documentation guide and update README with doc links
Co-authored-by: ketanMehtaa <45426198+ketanMehtaa@users.noreply.github.com>
1 parent 006458c commit 6695544

2 files changed

Lines changed: 327 additions & 0 deletions

File tree

‎DOCUMENTATION_GUIDE.md‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
# Twenty Project Documentation Guide
2+
3+
Welcome to the comprehensive documentation for the Twenty CRM project! This guide will help you navigate through the documentation and find the information you need.
4+
5+
## 📚 Documentation Overview
6+
7+
This repository contains extensive documentation covering all aspects of the Twenty project. Whether you're a new contributor, a developer working with the codebase, or someone interested in understanding the architecture, you'll find detailed information here.
8+
9+
## 🗂️ Documentation Structure
10+
11+
### Core Documentation Files
12+
13+
1. **[PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md)** - Start here!
14+
- Complete overview of the Twenty project
15+
- High-level architecture diagrams
16+
- Monorepo structure explanation
17+
- Technology stack details
18+
- Key features and capabilities
19+
- Development workflow guide
20+
- Links to all other resources
21+
22+
2. **[FRONTEND_ARCHITECTURE.md](./FRONTEND_ARCHITECTURE.md)** - Frontend deep dive
23+
- React application structure
24+
- Module-based architecture
25+
- State management with Recoil
26+
- GraphQL integration with Apollo Client
27+
- Routing with React Router
28+
- Styling with Emotion
29+
- Component library (UI module)
30+
- Development guidelines and best practices
31+
32+
3. **[BACKEND_ARCHITECTURE.md](./BACKEND_ARCHITECTURE.md)** - Backend deep dive
33+
- NestJS application structure
34+
- Core engine architecture
35+
- Dynamic metadata system
36+
- Multi-tenant workspace architecture
37+
- GraphQL API layer
38+
- Database design with PostgreSQL and TypeORM
39+
- Background job processing with BullMQ
40+
- Key business modules
41+
42+
## 🎯 Quick Start Guide
43+
44+
### For New Contributors
45+
46+
1. **Read [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md)** to understand the overall architecture
47+
2. **Set up your development environment** following the [Development Workflow](./PROJECT_OVERVIEW.md#development-workflow) section
48+
3. **Read the specific architecture docs** based on what you'll be working on:
49+
- Frontend work? → [FRONTEND_ARCHITECTURE.md](./FRONTEND_ARCHITECTURE.md)
50+
- Backend work? → [BACKEND_ARCHITECTURE.md](./BACKEND_ARCHITECTURE.md)
51+
52+
### For Frontend Developers
53+
54+
1. Start with [FRONTEND_ARCHITECTURE.md](./FRONTEND_ARCHITECTURE.md)
55+
2. Explore the [Core Modules](./FRONTEND_ARCHITECTURE.md#core-modules) section
56+
3. Review [State Management](./FRONTEND_ARCHITECTURE.md#state-management) patterns
57+
4. Check [Development Guidelines](./FRONTEND_ARCHITECTURE.md#development-guidelines)
58+
59+
### For Backend Developers
60+
61+
1. Start with [BACKEND_ARCHITECTURE.md](./BACKEND_ARCHITECTURE.md)
62+
2. Understand the [Metadata System](./BACKEND_ARCHITECTURE.md#metadata-system)
63+
3. Learn about [Workspace Architecture](./BACKEND_ARCHITECTURE.md#workspace-architecture)
64+
4. Review [Development Guidelines](./BACKEND_ARCHITECTURE.md#development-guidelines)
65+
66+
## 📖 Detailed Documentation
67+
68+
### Project Architecture
69+
70+
```
71+
┌─────────────────────────────────────────────────────────────┐
72+
│ Twenty Platform │
73+
├─────────────────────────────────────────────────────────────┤
74+
│ │
75+
│ ┌──────────────────┐ ┌──────────────────┐ │
76+
│ │ twenty-front │◄──────►│ twenty-server │ │
77+
│ │ (React SPA) │ API │ (NestJS API) │ │
78+
│ └──────────────────┘ └──────────────────┘ │
79+
│ │ │ │
80+
│ ▼ ▼ │
81+
│ ┌──────────────────┐ ┌──────────────────┐ │
82+
│ │ twenty-ui │ │ PostgreSQL │ │
83+
│ │ (UI Components) │ │ Database │ │
84+
│ └──────────────────┘ └──────────────────┘ │
85+
│ │ │
86+
│ ▼ │
87+
│ ┌──────────────────┐ │
88+
│ │ Redis │ │
89+
│ │ (Cache) │ │
90+
│ └──────────────────┘ │
91+
└─────────────────────────────────────────────────────────────┘
92+
```
93+
94+
### Monorepo Packages
95+
96+
The Twenty project is organized as a monorepo with the following main packages:
97+
98+
- **twenty-front**: React frontend application
99+
- **twenty-server**: NestJS backend API
100+
- **twenty-ui**: Shared UI component library
101+
- **twenty-shared**: Shared types and utilities
102+
- **twenty-emails**: Email templates
103+
- **twenty-website**: Documentation website
104+
- **twenty-zapier**: Zapier integration
105+
- **twenty-e2e-testing**: End-to-end tests
106+
107+
For complete details, see [Monorepo Structure](./PROJECT_OVERVIEW.md#monorepo-structure).
108+
109+
## 🔧 Development Commands
110+
111+
### Quick Reference
112+
113+
```bash
114+
# Start full development environment
115+
yarn start
116+
117+
# Frontend development
118+
npx nx start twenty-front
119+
npx nx test twenty-front
120+
npx nx lint twenty-front
121+
122+
# Backend development
123+
npx nx start twenty-server
124+
npx nx test twenty-server
125+
npx nx run twenty-server:worker
126+
127+
# Database operations
128+
npx nx database:reset twenty-server
129+
npx nx run twenty-server:database:migrate:prod
130+
```
131+
132+
For a complete list of commands, see [Development Workflow](./PROJECT_OVERVIEW.md#development-workflow).
133+
134+
## 🏗️ Architecture Highlights
135+
136+
### Frontend Architecture
137+
138+
- **Framework**: React 18 with TypeScript
139+
- **State Management**: Recoil for global state
140+
- **Data Fetching**: Apollo Client for GraphQL
141+
- **Styling**: Emotion (CSS-in-JS)
142+
- **Build Tool**: Vite
143+
144+
**Key Features:**
145+
- Module-based architecture
146+
- Dynamic component rendering based on metadata
147+
- Real-time updates via GraphQL subscriptions
148+
- Comprehensive Storybook component documentation
149+
150+
[Learn more →](./FRONTEND_ARCHITECTURE.md)
151+
152+
### Backend Architecture
153+
154+
- **Framework**: NestJS with TypeScript
155+
- **Database**: PostgreSQL with TypeORM
156+
- **API**: Dynamic GraphQL schema generation
157+
- **Jobs**: BullMQ for background processing
158+
- **Cache**: Redis
159+
160+
**Key Features:**
161+
- Multi-tenant workspace isolation
162+
- Dynamic schema generation from metadata
163+
- Flexible field and object type system
164+
- Comprehensive workflow automation engine
165+
166+
[Learn more →](./BACKEND_ARCHITECTURE.md)
167+
168+
## 🎨 Key Features Explained
169+
170+
### 1. Dynamic Metadata System
171+
172+
Twenty's metadata system allows users to create custom objects and fields without code changes. The backend generates:
173+
- GraphQL schema
174+
- Database tables
175+
- API resolvers
176+
- Type definitions
177+
178+
[Metadata System Details →](./BACKEND_ARCHITECTURE.md#metadata-system)
179+
180+
### 2. Multi-Tenant Architecture
181+
182+
Each workspace operates in complete isolation:
183+
- Separate PostgreSQL schema
184+
- Independent GraphQL schema
185+
- Isolated data storage
186+
- Custom metadata per workspace
187+
188+
[Workspace Architecture Details →](./BACKEND_ARCHITECTURE.md#workspace-architecture)
189+
190+
### 3. View System
191+
192+
Flexible data presentation with:
193+
- Multiple view types (Table, Kanban)
194+
- Advanced filtering with AND/OR logic
195+
- Multi-column sorting
196+
- Group by functionality
197+
- Personal and shared views
198+
199+
[Views Module Details →](./FRONTEND_ARCHITECTURE.md#core-modules)
200+
201+
### 4. Workflow Automation
202+
203+
Powerful automation capabilities:
204+
- Various trigger types (record events, scheduled, webhook)
205+
- Multiple actions (update record, send email, webhook, code)
206+
- Conditional execution
207+
- Version management
208+
209+
[Workflow Module Details →](./BACKEND_ARCHITECTURE.md#key-business-modules)
210+
211+
## 🧪 Testing Strategy
212+
213+
- **Unit Tests**: Jest for both frontend and backend
214+
- **Integration Tests**: Backend API testing with database
215+
- **E2E Tests**: Playwright for critical user flows
216+
- **Component Tests**: Storybook for UI components
217+
- **Visual Regression**: Chromatic for visual testing
218+
219+
## 📚 Additional Resources
220+
221+
### Official Documentation
222+
223+
- [Official Website](https://twenty.com)
224+
- [Developer Documentation](https://twenty.com/developers)
225+
- [Local Setup Guide](https://twenty.com/developers/local-setup)
226+
- [Self-Hosting Guide](https://twenty.com/developers/section/self-hosting)
227+
228+
### Repository Documentation
229+
230+
Located in `packages/twenty-website/src/content/developers/`:
231+
232+
**Frontend:**
233+
- [Folder Architecture](./packages/twenty-website/src/content/developers/frontend-development/folder-architecture-front.mdx)
234+
- [Frontend Commands](./packages/twenty-website/src/content/developers/frontend-development/frontend-commands.mdx)
235+
- [Style Guide](./packages/twenty-website/src/content/developers/frontend-development/style-guide.mdx)
236+
- [Best Practices](./packages/twenty-website/src/content/developers/frontend-development/best-practices-front.mdx)
237+
238+
**Backend:**
239+
- [Folder Architecture](./packages/twenty-website/src/content/developers/backend-development/folder-architecture-server.mdx)
240+
- [Server Commands](./packages/twenty-website/src/content/developers/backend-development/server-commands.mdx)
241+
- [Best Practices](./packages/twenty-website/src/content/developers/backend-development/best-practices-server.mdx)
242+
- [Custom Objects](./packages/twenty-website/src/content/developers/backend-development/custom-objects.mdx)
243+
244+
### Community Resources
245+
246+
- [Discord Server](https://discord.gg/cx5n4Jzs57) - Join the community
247+
- [GitHub Discussions](https://github.com/twentyhq/twenty/discussions) - Ask questions
248+
- [Contributing Guide](https://github.com/twentyhq/twenty/blob/main/.github/CONTRIBUTING.md) - Contribute to the project
249+
- [Figma Design Files](https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty) - View designs
250+
251+
### API Documentation
252+
253+
- [GraphQL API Documentation](https://twenty.com/developers/graphql-apis)
254+
- [REST API Documentation](https://twenty.com/developers/rest-apis)
255+
- [Webhooks Documentation](https://twenty.com/developers/api-and-webhooks)
256+
257+
## 🤝 Contributing
258+
259+
We welcome contributions! Here's how to get started:
260+
261+
1. **Read the documentation** (you're already doing this! 🎉)
262+
2. **Set up your development environment** using the [Development Workflow](./PROJECT_OVERVIEW.md#development-workflow) guide
263+
3. **Find an issue** to work on or propose a new feature
264+
4. **Follow the code style** and [Development Guidelines](./FRONTEND_ARCHITECTURE.md#development-guidelines)
265+
5. **Submit a pull request** with your changes
266+
267+
For detailed contribution guidelines, see the [Contributing Guide](https://github.com/twentyhq/twenty/blob/main/.github/CONTRIBUTING.md).
268+
269+
## 📝 Documentation Updates
270+
271+
These documentation files are actively maintained. If you find any errors or have suggestions for improvements:
272+
273+
1. Open an issue describing the problem or improvement
274+
2. Submit a pull request with your changes
275+
3. Tag your PR with the `documentation` label
276+
277+
## 🔍 Finding Information
278+
279+
Use this quick reference to find specific information:
280+
281+
| Looking for... | Check this file | Section |
282+
|---------------|----------------|---------|
283+
| Project overview | PROJECT_OVERVIEW.md | All sections |
284+
| Monorepo structure | PROJECT_OVERVIEW.md | Monorepo Structure |
285+
| Tech stack details | PROJECT_OVERVIEW.md or specific architecture docs | Technology Stack |
286+
| Frontend modules | FRONTEND_ARCHITECTURE.md | Core Modules |
287+
| State management | FRONTEND_ARCHITECTURE.md | State Management |
288+
| GraphQL integration | FRONTEND_ARCHITECTURE.md | GraphQL Integration |
289+
| Backend modules | BACKEND_ARCHITECTURE.md | Core Engine |
290+
| Metadata system | BACKEND_ARCHITECTURE.md | Metadata System |
291+
| Database design | BACKEND_ARCHITECTURE.md | Database Layer |
292+
| Workspace architecture | BACKEND_ARCHITECTURE.md | Workspace Architecture |
293+
| Background jobs | BACKEND_ARCHITECTURE.md | Background Jobs |
294+
| Development commands | PROJECT_OVERVIEW.md | Development Workflow |
295+
| Testing strategy | PROJECT_OVERVIEW.md or specific docs | Testing sections |
296+
297+
## 🚀 Next Steps
298+
299+
Now that you've found the documentation:
300+
301+
1. **For new contributors**: Start with [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md)
302+
2. **For frontend work**: Read [FRONTEND_ARCHITECTURE.md](./FRONTEND_ARCHITECTURE.md)
303+
3. **For backend work**: Read [BACKEND_ARCHITECTURE.md](./BACKEND_ARCHITECTURE.md)
304+
4. **Set up your environment**: Follow the [Development Workflow](./PROJECT_OVERVIEW.md#development-workflow)
305+
5. **Join the community**: [Discord](https://discord.gg/cx5n4Jzs57) or [GitHub Discussions](https://github.com/twentyhq/twenty/discussions)
306+
307+
## 📧 Questions?
308+
309+
If you have questions not covered in the documentation:
310+
311+
- Check [GitHub Discussions](https://github.com/twentyhq/twenty/discussions)
312+
- Join the [Discord Server](https://discord.gg/cx5n4Jzs57)
313+
- Open an issue with the `question` label
314+
315+
---
316+
317+
**Happy coding!** 🎉
318+
319+
Built with ❤️ by the Twenty community

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,14 @@
2424

2525
<br />
2626

27+
# Documentation
28+
29+
📖 **[Complete Project Documentation](./DOCUMENTATION_GUIDE.md)** - Start here for comprehensive documentation!
30+
31+
- [Project Overview](./PROJECT_OVERVIEW.md) - Architecture, tech stack, and development workflow
32+
- [Frontend Architecture](./FRONTEND_ARCHITECTURE.md) - React, Recoil, GraphQL, and component structure
33+
- [Backend Architecture](./BACKEND_ARCHITECTURE.md) - NestJS, metadata system, and workspace architecture
34+
2735
# Installation
2836

2937
See:

0 commit comments

Comments
 (0)