1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
| # Architecture Overview
This document serves as a critical, living template designed to equip agents with a rapid and comprehensive understanding of the codebase's architecture, enabling efficient navigation and effective contribution from day one. Update this document as the codebase evolves.
## 1. Project Structure
This section provides a high-level overview of the project's directory and file structure, categorised by architectural layer or major functional area. It is essential for quickly navigating the codebase, locating relevant files, and understanding the overall organization and separation of concerns.
[Project Root]/
├── backend/ # Contains all server-side code and APIs
│ ├── src/ # Main source code for backend services
│ │ ├── api/ # API endpoints and controllers
│ │ ├── client/ # Business logic and service implementations
│ │ ├── models/ # Database models/schemas
│ │ └── utils/ # Backend utility functions
│ ├── config/ # Backend configuration files
│ ├── tests/ # Backend unit and integration tests
│ └── Dockerfile # Dockerfile for backend deployment
├── frontend/ # Contains all client-side code for user interfaces
│ ├── src/ # Main source code for frontend applications
│ │ ├── components/ # Reusable UI components
│ │ ├── pages/ # Application pages/views
│ │ ├── assets/ # Images, fonts, and other static assets
│ │ ├── services/ # Frontend services for API interaction
│ │ └── store/ # State management (e.g., Redux, Vuex, Context API)
│ ├── public/ # Publicly accessible assets (e.g., index.html)
│ ├── tests/ # Frontend unit and E2E tests
│ └── package.json # Frontend dependencies and scripts
├── common/ # Shared code, types, and utilities used by both frontend and backend
│ ├── types/ # Shared TypeScript/interface definitions
│ └── utils/ # General utility functions
├── docs/ # Project documentation (e.g., API docs, setup guides)
├── scripts/ # Automation scripts (e.g., deployment, data seeding)
├── .github/ # GitHub Actions or other CI/CD configurations
├── .gitignore # Specifies intentionally untracked files to ignore
├── README.md # Project overview and quick start guide
└── ARCHITECTURE.md # This document
## 2. High-Level System Diagram
Provide a simple block diagram (e.g., a C4 Model Level 1: System Context diagram, or a basic component diagram) or a clear text-based description of the major components and their interactions. Focus on how data flows, services communicate, and key architectural boundaries.
[User] <--> [Frontend Application] <--> [Backend Service 1] <--> [Database 1]
|
+--> [Backend Service 2] <--> [External API]
## 3. Core Components
(List and briefly describe the main components of the system. For each, include its primary responsibility and key technologies used.)
### 3.1. Frontend
Name: [e.g., Web App, Mobile App]
Description: Briefly describe its primary purpose, key functionalities, and how users or other systems interact with it. E.g., 'The main user interface for interacting with the system, allowing users to manage their profiles, view data dashboards, and initiate workflows.'
Technologies: [e.g., React, Next.js, Vue.js, Swift/Kotlin, HTML/CSS/JS]
Deployment: [e.g., Vercel, Netlify, S3/CloudFront]
### 3.2. Backend Services
(Repeat for each significant backend service. Add more as needed.)
#### 3.2.1. [Service Name 1]
Name: [e.g., User Management Service, Data Processing API]
Description: [Briefly describe its purpose, e.g., "Handles user authentication and profile management."]
Technologies: [e.g., Node.js (Express), Python (Django/Flask), Java (Spring Boot), Go]
Deployment: [e.g., AWS EC2, Kubernetes, Serverless (Lambda/Cloud Functions)]
#### 3.2.2. [Service Name 2]
Name: [e.g., Analytics Service, Notification Service]
Description: [Briefly describe its purpose.]
Technologies: [e.g., Python, Kafka, Redis]
Deployment: [e.g., AWS ECS, Google Cloud Run]
## 4. Data Stores
(List and describe the databases and other persistent storage solutions used.)
### 4.1. [Data Store Type 1]
Name: [e.g., Primary User Database, Analytics Data Warehouse]
Type: [e.g., PostgreSQL, MongoDB, Redis, S3, Firestore]
Purpose: [Briefly describe what data it stores and why.]
Key Schemas/Collections: [List important tables/collections, e.g., users, products, orders (no need for full schema, just names)]
### 4.2. [Data Store Type 2]
Name: [e.g., Cache, Message Queue]
Type: [e.g., Redis, Kafka, RabbitMQ]
Purpose: [Briefly describe its purpose, e.g., "Used for caching frequently accessed data" or "Inter-service communication."]
## 5. External Integrations / APIs
(List any third-party services or external APIs the system interacts with.)
Service Name 1: [e.g., Stripe, SendGrid, Google Maps API]
Purpose: [Briefly describe its function, e.g., "Payment processing."]
Integration Method: [e.g., REST API, SDK]
## 6. Deployment & Infrastructure
Cloud Provider: [e.g., AWS, GCP, Azure, On-premise]
Key Services Used: [e.g., EC2, Lambda, S3, RDS, Kubernetes, Cloud Functions, App Engine]
CI/CD Pipeline: [e.g., GitHub Actions, GitLab CI, Jenkins, CircleCI]
Monitoring & Logging: [e.g., Prometheus, Grafana, CloudWatch, Stackdriver, ELK Stack]
## 7. Security Considerations
(Highlight any critical security aspects, authentication mechanisms, or data encryption practices.)
Authentication: [e.g., OAuth2, JWT, API Keys]
Authorization: [e.g., RBAC, ACLs]
Data Encryption: [e.g., TLS in transit, AES-256 at rest]
Key Security Tools/Practices: [e.g., WAF, regular security audits]
## 8. Development & Testing Environment
Local Setup Instructions: [Link to CONTRIBUTING.md or brief steps]
Testing Frameworks: [e.g., Jest, Pytest, JUnit]
Code Quality Tools: [e.g., ESLint, Black, SonarQube]
## 9. Future Considerations / Roadmap
(Briefly note any known architectural debts, planned major changes, or significant future features that might impact the architecture.)
[e.g., "Migrate from monolith to microservices."]
[e.g., "Implement event-driven architecture for real-time updates."]
## 10. Project Identification
Project Name: [Insert Project Name]
Repository URL: [Insert Repository URL]
Primary Contact/Team: [Insert Lead Developer/Team Name]
Date of Last Update: [YYYY-MM-DD]
## 11. Glossary / Acronyms
Define any project-specific terms or acronyms.)
[Acronym]: [Full Definition]
[Term]: [Explanation]
|