Barazo lexicon schemas and TypeScript types
barazo.forum
Merge pull request #1 from atgora-forum/docs/add-readme-and-templates
docs: add README, PR template, and security policy
authored by
Guido X Jansen
and committed by
GitHub
37ea741c
c6920dd4
+240
+69
.github/PULL_REQUEST_TEMPLATE.md
+69
.github/PULL_REQUEST_TEMPLATE.md
···
1
+
## Description
2
+
3
+
<!-- What does this PR do? Why is it needed? -->
4
+
5
+
Closes #<!-- issue number -->
6
+
7
+
## Type of Change
8
+
9
+
- [ ] Bug fix (non-breaking change which fixes an issue)
10
+
- [ ] New feature (non-breaking change which adds functionality)
11
+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
12
+
- [ ] Documentation update
13
+
- [ ] Refactor (no functional changes)
14
+
- [ ] Dependency update
15
+
- [ ] CI/CD changes
16
+
17
+
## Testing
18
+
19
+
<!-- How was this tested? What scenarios were covered? -->
20
+
21
+
- [ ] Unit tests added/updated
22
+
- [ ] Integration tests added/updated
23
+
- [ ] Manual testing performed
24
+
- [ ] Accessibility tested (if UI changes)
25
+
- [ ] Tested in staging environment
26
+
- [ ] All tests pass locally (`pnpm test`)
27
+
28
+
**Test coverage:** <!-- e.g., "Added 5 unit tests, 2 integration tests" -->
29
+
30
+
## Checklist
31
+
32
+
- [ ] Code follows conventional commit format
33
+
- [ ] Self-review completed (read own diff on GitHub)
34
+
- [ ] No TypeScript errors (`pnpm typecheck`)
35
+
- [ ] No ESLint warnings (`pnpm lint`)
36
+
- [ ] Documentation updated (if applicable)
37
+
- [ ] Database migration included (if schema changed)
38
+
- [ ] Breaking changes documented below (if applicable)
39
+
- [ ] CI checks pass
40
+
- [ ] No secrets or credentials in code
41
+
42
+
## Breaking Changes
43
+
44
+
<!-- If this is a breaking change, describe:
45
+
1. What breaks?
46
+
2. How should users migrate?
47
+
3. Link to migration guide (if exists)
48
+
-->
49
+
50
+
**None** / <!-- Describe breaking changes here -->
51
+
52
+
## Screenshots/Logs (if applicable)
53
+
54
+
<!-- Add screenshots for UI changes, or logs for backend changes -->
55
+
56
+
## Additional Context
57
+
58
+
<!-- Any other information reviewers should know -->
59
+
60
+
## Reviewer Checklist
61
+
62
+
<!-- For reviewers - don't fill this out yourself -->
63
+
64
+
- [ ] Code quality meets standards
65
+
- [ ] Tests are meaningful and cover edge cases
66
+
- [ ] Security considerations addressed
67
+
- [ ] Performance impact acceptable
68
+
- [ ] Accessibility compliant (if UI)
69
+
- [ ] Documentation clear and complete
+37
.github/SECURITY.md
+37
.github/SECURITY.md
···
1
+
# Security Policy
2
+
3
+
## Supported Versions
4
+
5
+
| Version | Supported |
6
+
| ------- | ------------------ |
7
+
| 1.x | :white_check_mark: |
8
+
| < 1.0 | :x: |
9
+
10
+
## Reporting a Vulnerability
11
+
12
+
**Do not open a public issue for security vulnerabilities.**
13
+
14
+
Instead, use GitHub's private vulnerability reporting:
15
+
16
+
1. Go to the repository
17
+
2. Click "Security" tab
18
+
3. Click "Report a vulnerability"
19
+
4. Fill in the details
20
+
21
+
Or email: security@atgora.forum (TBD - will be set up in Phase 2)
22
+
23
+
We will respond within 72 hours with next steps.
24
+
25
+
## Security Practices
26
+
27
+
- All commits must be GPG signed
28
+
- Dependencies updated weekly via Dependabot
29
+
- CI runs security scans on every PR
30
+
- OWASP Top 10 compliance verified
31
+
32
+
## Disclosure Policy
33
+
34
+
We follow responsible disclosure:
35
+
- 90 days before public disclosure
36
+
- Credit given to reporter (if desired)
37
+
- CVE assigned when applicable
+134
README.md
+134
README.md
···
1
+
# atgora-lexicons
2
+
3
+
**AT Protocol schemas for ATgora forums**
4
+
5
+
[](https://opensource.org/licenses/MIT)
6
+
[](https://github.com/atgora-forum/atgora-lexicons/packages)
7
+
8
+
---
9
+
10
+
## 🚧 Status: Pre-Alpha Development
11
+
12
+
AT Protocol lexicon schemas for the ATgora forum platform.
13
+
14
+
**Current phase:** Planning complete, schema design starting Q1 2026
15
+
16
+
---
17
+
18
+
## What is this?
19
+
20
+
The atgora-lexicons repo defines the **data format** for forum content on the AT Protocol. It produces:
21
+
22
+
1. **Lexicon JSON schemas** - AT Protocol record definitions
23
+
2. **TypeScript types** - Generated from schemas
24
+
3. **Zod validation schemas** - Runtime validation
25
+
4. **npm package** - `@atgora-forum/lexicons` used by atgora-api and atgora-web
26
+
27
+
**This is the source of truth** for all `forum.atgora.*` record types.
28
+
29
+
---
30
+
31
+
## Record Types (MVP)
32
+
33
+
**Core records:**
34
+
- `forum.atgora.topic.post` - Forum topics
35
+
- `forum.atgora.topic.reply` - Replies to topics
36
+
- `forum.atgora.interaction.reaction` - Reactions (likes, etc.)
37
+
- `forum.atgora.actor.preferences` - User moderation preferences (stored on user's PDS)
38
+
39
+
**Archive records (Phase 5):**
40
+
- `forum.atgora.archivedPost` - Migrated content from legacy forums
41
+
42
+
---
43
+
44
+
## Installation
45
+
46
+
```bash
47
+
# From GitHub Packages
48
+
npm config set @atgora-forum:registry https://npm.pkg.github.com
49
+
pnpm add @atgora-forum/lexicons
50
+
```
51
+
52
+
---
53
+
54
+
## Usage
55
+
56
+
```typescript
57
+
import { TopicPost, topicPostSchema } from '@atgora-forum/lexicons'
58
+
59
+
// TypeScript type
60
+
const post: TopicPost = {
61
+
$type: 'forum.atgora.topic.post',
62
+
title: 'Hello World',
63
+
content: 'This is a forum topic',
64
+
forum: 'did:plc:abc123',
65
+
category: 'general',
66
+
createdAt: new Date().toISOString()
67
+
}
68
+
69
+
// Runtime validation
70
+
const validated = topicPostSchema.parse(post)
71
+
```
72
+
73
+
---
74
+
75
+
## Development
76
+
77
+
**Prerequisites:**
78
+
- Node.js 24 LTS
79
+
- pnpm
80
+
81
+
**Setup:**
82
+
```bash
83
+
git clone https://github.com/atgora-forum/atgora-lexicons.git
84
+
cd atgora-lexicons
85
+
pnpm install
86
+
```
87
+
88
+
**Commands:**
89
+
```bash
90
+
pnpm test # Validate schemas + run tests
91
+
pnpm test:schemas # Validate lexicon JSON files
92
+
pnpm test:types # Verify TypeScript generation
93
+
pnpm build # Generate TypeScript types
94
+
```
95
+
96
+
---
97
+
98
+
## Versioning
99
+
100
+
**Independent semver** - Lexicons version separately from API/Web.
101
+
102
+
- **MAJOR:** Breaking schema changes (rare - create new record type instead)
103
+
- **MINOR:** Add optional fields
104
+
- **PATCH:** Documentation, no schema changes
105
+
106
+
**Breaking changes:** Create new lexicon ID (e.g., `forum.atgora.topic.postV2`)
107
+
108
+
See [standards/shared.md](https://github.com/atgora-forum/atgora-forum/blob/main/standards/shared.md#versioning--release-strategy) for full versioning strategy.
109
+
110
+
---
111
+
112
+
## License
113
+
114
+
**MIT** - Maximum adoption. We want the `forum.atgora.*` namespace to become a true open standard.
115
+
116
+
---
117
+
118
+
## Related Repositories
119
+
120
+
- **[atgora-api](https://github.com/atgora-forum/atgora-api)** - Consumes these types for validation
121
+
- **[atgora-web](https://github.com/atgora-forum/atgora-web)** - Uses types for API responses
122
+
- **[Organization](https://github.com/atgora-forum)** - All repos
123
+
124
+
---
125
+
126
+
## Community
127
+
128
+
- 🌐 **Website:** [atgora.forum](https://atgora.forum) (coming soon)
129
+
- 💬 **Discussions:** [GitHub Discussions](https://github.com/orgs/atgora-forum/discussions)
130
+
- 📖 **AT Protocol Docs:** [atproto.com](https://atproto.com/)
131
+
132
+
---
133
+
134
+
© 2026 ATgora. Licensed under MIT.